PyPI 官网下载 | firebird-driver-1.0.0.tar.gz

=========== Usage Guide =========== .. currentModule:: firebird.driver Driver structure ================ Source code is currently divided into next submodules: * :mod:`~firebird.driver.types` - Data types used by driver. * :mod:`~firebird.driver.interfaces` - Interface wrappers for Firebird new API * :mod:`~firebird.driver.core` - Main driver source code. * :mod:`~firebird.driver.fbapi` - Python `ctypes` interface to Firebird client library. * :mod:`~firebird.driver.config` - Driver configuration. * :mod:`~firebird.driver.hooks` - Drivers hooks. All important data, functions, classes and constants are available directly in `firebird.driver` name space. In normal circumstances is not necessary to import sub-modules directly. However, you may need them to access some not so frequently needed driver functionality like driver hooks, or to implement your own callback interfaces. .. index:: Configuration Configuration ============= The driver uses configuration built on top of `configuration system <firebird.base.config>` provided by `firebird-base`_ package. In addition to global settings, the configuration also includes the definition of connection parameters to Firebird servers and databases. The default configuration connects to embedded server using direct/local connection method. To access remote servers and databases (or local ones through remote protocols), it's necessary to adjust default configuration, or `register` them in configuration manager. You can manipulate the configuration objects directly, or load configuration from files or strings (in `.ini-style` `configparser` format). The 'driver_config' object -------------------------- The global `.driver_config` object holds all configurable driver parameters, and access configuration parameters for registered Firebird servers and databases. In initial state, all parameters have default values and there are no registered servers and databases. You can set individual parameter values directly, or you can set multiple parameters (including registered servers and databases) at once by loading them from configuration string, dict or file(s). .. important:: If you want to use specific Firebird client library, you must set the value of `.DriverConfig.fb_client_library` configuration option **before** your application calls any from following functions: `.connect()`, `.create_database()`, `.connect_server()`, `.load_api()` or `.get_api()`. .. seealso:: `.DriverConfig` for list of available methods and parameters. Server and database configuration --------------------------------- Firebird provides ever-increasing list of parameter options for database and server connections. To keep the Python API clean and manageable, the `firebird-driver` uses server and database configuration objects instead function parameters to specify values for almost all such options. Connection functions then provide a name parameter that can refer to particular server / database or configuration, and few keyword parameters to specify / override selected options. .. important:: The configuration objects does not allow specification of next options: - set database encryption callback (for technical reasons) - set db_key scope (for security reasons) - disable garbage collection (for security reasons) - disable database triggers (for security reasons) - allow overwrite of existing database with newly created database (for security reasons) These options could be specified only as keyword arguments in appropriate functions. .. seealso:: `.ServerConfig` and `.DatabaseConfig` for list of available methods and parameters. .. index:: Database pair: Connection; creation Databases ========= Access to the database is made available through `.Connection` objects. Firebird-driver provides two constructors for these: * `.connect` - Returns `.Connection` to database that already exists. * `.create_database` - Returns `.Connection` to newly created database. .. index:: pair: Database; connect Using connect() --------------- This constructor has one positional and several keyword parameters. The value of `database` positional parameter must be one of: * name of registered database configuration * database name / alias .. important:: This value **cannot** be DSN / fully qualified Firebird connection string! Keyword parameters are intended to override selected configuration options, or to specify options that are not configurable. .. note:: If `database` value is not recognized as name of registered database configuration, the driver uses `~.DriverConfig.db_defaults` and `~.DriverConfig.server_defaults` configuration objects. A simple database connection is typically established with code such as this: .. sourcecode:: python from firebird.driver import connect # Attach to 'employee' database/alias using embedded server connection con = connect('employee', user='sysdba', password='masterkey') # Attach to 'employee' database/alias using local server connection from firebird.driver import driver_config driver_config.server_defaults.host.value = 'localhost' con = connect('employee', user='sysdba', password='masterkey') # Set 'user' and 'password' via configuration driver_config.server_defaults.user.value = 'SYSDBA' driver_config.server_defaults.password.value = 'masterkey' con = connect('employee') However, it's recommended to use specific configuration for servers and databases. It's possible to register servers and databases directly in code like this: .. sourcecode:: python from firebird.driver import connect, driver_config # Register Firebird server srv_cfg = """[local] host = localhost user = SYSDBA password = masterkey """ driver_config.register_server('local', srv_cfg) # Register database db_cfg = """[employee] server = local database = employee.fdb protocol = inet charset = utf8 """ driver_config.register_database('employee', db_cfg) # Attach to 'employee' database con = connect('employee') But more convenient approach is using single configuration file:: # file: myapp.cfg [firebird.driver] servers = local databases = employee [local] host = localhost user = SYSDBA password = masterkey [employee] server = local database = employee.fdb protocol = inet charset = utf8 .. sourcecode:: python from firebird.driver import connect, driver_config driver_config.read('myapp.cfg') # Attach to 'employee' database con = connect('employee') .. seealso:: `.connect()` for details. .. index:: pair: Database; create Using create_database() ----------------------- This constructor returns connection to newly created database. It works in the same way as `.connect()`, but utilizes additional database configuration options. It's possible to specify these options in code like this: .. sourcecode:: python from firebird.driver import connect, driver_config # Register Firebird server srv_cfg = """[local] host = localhost user = SYSDBA password = masterkey """ driver_config.register_server('local', srv_cfg) # Register database db_cfg = """[mydb] server = local database = mydb.fdb protocol = inet charset = utf8 # create options page_size = 16384 db_charset = utf8 sweep_interval = 80000 reserve_space = no """ driver_config.register_database('mydb', db_cfg) # create 'mydb' database con = create_database('mydb') But more convenient approach is using single configuration file:: # file: myapp.cfg [firebird.driver] servers = local databases = mydb [local] host = localhost user = SYSDBA password = masterkey [mydb] server = local database = mydb.fdb protocol = inet charset = utf8 # create options page_size = 16384