Skip to content

Database

database

Classes:

  • Database –

    Provides access and control over the loaded IDA database.

  • DatabaseError –

    Exception for database operations.

  • DatabaseMetadata –

    Metadata information about the current database.

  • IdaCommandOptions –

    Configuration for building IDA command line arguments.

Database 

Database(hooks: HooksList = [])

Provides access and control over the loaded IDA database.

Can be used as a context manager for automatic resource cleanup.

Args: hooks (HooksList, optional): A list of hook instances to associate with this database. Defaults to an empty list.

Note: Direct instantiation of this class is discouraged. Use the Database.open() class method to create and initialize a database instance.

Example: 

# Open and automatically close a database
with Database.open("path/to/file.exe", save_on_close=True) as db:
    # Work with the database
    print(f"Loaded: {db.path}")
# Database is automatically closed here

# Or use without context manager
db = Database.open("path/to/file.exe", save_on_close=True)
# Work with database
db.close()  # Uses save_on_close=True automatically

Methods:

  • close –

    Closes the currently open database.

  • hook –

    Activate (hook) all registered event handler instances.

  • is_open –

    Checks if the database is loaded.

  • is_valid_ea –

    Check if the specified address is valid.

  • open –

    Database factory, opens a database from the specified file path.

  • unhook –

    Deactivate (unhook) all registered event handler instances.

Attributes:

  • architecture (Optional[str]) –

    The processor architecture.

  • base_address (Optional[ea_t]) –

    The image base address of this database.

  • basic_blocks (BasicBlocks) –

    Handler that provides access to basic block-related operations.

  • bitness (Optional[int]) –

    The application bitness (32/64).

  • bytes (Bytes) –

    Handler that provides access to byte-level memory operations.

  • comments (Comments) –

    Handler that provides access to user comment-related operations.

  • crc32 (Optional[int]) –

    The CRC32 checksum of the input file.

  • current_ea (ea_t) –

    The current effective address (equivalent to the "screen EA" in IDA GUI).

  • entries (Entries) –

    Handler that provides access to entries operations.

  • filesize (Optional[int]) –

    The input file size.

  • format (Optional[str]) –

    The file format type.

  • functions (Functions) –

    Handler that provides access to function-related operations.

  • heads (Heads) –

    Handler that provides access to user heads operations.

  • hooks (HooksList) –

    Returns the list of associated hook instances.

  • instructions (Instructions) –

    Handler that provides access to instruction-related operations.

  • load_time (Optional[str]) –

    The database load time.

  • maximum_ea (ea_t) –

    The maximum effective address from this database.

  • md5 (Optional[str]) –

    The MD5 hash of the input file.

  • metadata (DatabaseMetadata) –

    Map of key-value metadata about the current database.

  • minimum_ea (ea_t) –

    The minimum effective address from this database.

  • module (Optional[str]) –

    The module name.

  • names (Names) –

    Handler that provides access to name-related operations.

  • path (Optional[str]) –

    The input file path.

  • save_on_close –
  • segments (Segments) –

    Handler that provides access to memory segment-related operations.

  • sha256 (Optional[str]) –

    The SHA256 hash of the input file.

  • signature_files (SignatureFiles) –

    Handler that provides access to signature file operations.

  • strings (Strings) –

    Handler that provides access to string-related operations.

  • types (Types) –

    Handler that provides access to type-related operations.

  • xrefs (Xrefs) –

    Handler that provides access to cross-reference (xref) operations.

architecture property 

architecture: Optional[str]

The processor architecture.

base_address property 

base_address: Optional[ea_t]

The image base address of this database.

basic_blocks property 

basic_blocks: BasicBlocks

Handler that provides access to basic block-related operations.

bitness property 

bitness: Optional[int]

The application bitness (32/64).

bytes property 

bytes: Bytes

Handler that provides access to byte-level memory operations.

comments property 

comments: Comments

Handler that provides access to user comment-related operations.

crc32 property 

crc32: Optional[int]

The CRC32 checksum of the input file.

current_ea property writable 

current_ea: ea_t

The current effective address (equivalent to the "screen EA" in IDA GUI).

entries property 

entries: Entries

Handler that provides access to entries operations.

filesize property 

filesize: Optional[int]

The input file size.

format property 

format: Optional[str]

The file format type.

functions property 

functions: Functions

Handler that provides access to function-related operations.

heads property 

heads: Heads

Handler that provides access to user heads operations.

hooks property 

hooks: HooksList

Returns the list of associated hook instances.

instructions property 

instructions: Instructions

Handler that provides access to instruction-related operations.

load_time property 

load_time: Optional[str]

The database load time.

maximum_ea property 

maximum_ea: ea_t

The maximum effective address from this database.

md5 property 

md5: Optional[str]

The MD5 hash of the input file.

metadata property 

metadata: DatabaseMetadata

Map of key-value metadata about the current database. Dynamically built from DatabaseMetadata dataclass fields. Returns metadata with original property types preserved.

minimum_ea property 

minimum_ea: ea_t

The minimum effective address from this database.

module property 

module: Optional[str]

The module name.

names property 

names: Names

Handler that provides access to name-related operations.

path property 

path: Optional[str]

The input file path.

save_on_close instance-attribute 

save_on_close = False

segments property 

segments: Segments

Handler that provides access to memory segment-related operations.

sha256 property 

sha256: Optional[str]

The SHA256 hash of the input file.

signature_files property 

signature_files: SignatureFiles

Handler that provides access to signature file operations.

strings property 

strings: Strings

Handler that provides access to string-related operations.

types property 

types: Types

Handler that provides access to type-related operations.

xrefs property 

xrefs: Xrefs

Handler that provides access to cross-reference (xref) operations.

close 

close(save: Optional[bool] = None) -> None

Closes the currently open database.

Args: save: If provided, saves/discards changes accordingly. If None, uses the save_on_close setting from open().

Note: This function is available only when running IDA as a library. When running inside the IDA GUI, we have no control on the database lifecycle.

hook 

hook() -> None

Activate (hook) all registered event handler instances.

This method associates each hook instance with the current database instance and calls their hook() method. Hooks are automatically hooked when the database is opened (including when used as a context manager).

Typically, you do not need to call this method manually—hooks are managed automatically upon database entry.

is_open 

is_open() -> bool

Checks if the database is loaded.

Returns: True if a database is open, false otherwise.

is_valid_ea 

is_valid_ea(ea: ea_t, strict_check: bool = True) -> bool

Check if the specified address is valid.

Args: ea: The effective address to validate. strict_check: If True, validates ea is mapped (ida_bytes.is_mapped). If False, only validates ea is within database range.

Returns: True if address is valid according to the check level.

open classmethod 

open(
    path: str = '',
    args: Optional[IdaCommandOptions] = None,
    save_on_close: bool = False,
    hooks: HooksList = [],
) -> Database

Database factory, opens a database from the specified file path.

Args: path: Path to the input file, pass None when running inside IDA GUI args: Command builder responsible for passing arguments to IDA kernel. save_on_close: Default behavior for saving changes on close. Used automatically when exiting context manager, but can be overridden in explicit close() calls. hooks: List of hook instances to associated with the database. Hooks are automatically enabled before opening the database and disabled after closing.

Returns: Database: A new Database instance on success

Raises: DatabaseError: If the Database instance cannot be created

Note: The user is allowed to open a new file only when running IDA as a library. When running inside the IDA GUI, the db_path needs to be set to None to refer to the currently open database in IDA.

unhook 

unhook() -> None

Deactivate (unhook) all registered event handler instances.

This method calls unhook() on each registered hook and disassociates them from the database instance. Hooks are automatically unhooked when the database is closed, including when used with the database as a context manager.

Typically, you do not need to call this method manually—hooks are managed automatically upon database exit.

DatabaseError

Bases: Exception

Exception for database operations.

DatabaseMetadata dataclass 

DatabaseMetadata(
    path: Optional[str] = None,
    module: Optional[str] = None,
    base_address: Optional[ea_t] = None,
    filesize: Optional[int] = None,
    md5: Optional[str] = None,
    sha256: Optional[str] = None,
    crc32: Optional[int] = None,
    architecture: Optional[str] = None,
    bitness: Optional[int] = None,
    format: Optional[str] = None,
    load_time: Optional[str] = None,
)

Metadata information about the current database.

Attributes:

architecture class-attribute instance-attribute 

architecture: Optional[str] = None

base_address class-attribute instance-attribute 

base_address: Optional[ea_t] = None

bitness class-attribute instance-attribute 

bitness: Optional[int] = None

crc32 class-attribute instance-attribute 

crc32: Optional[int] = None

filesize class-attribute instance-attribute 

filesize: Optional[int] = None

format class-attribute instance-attribute 

format: Optional[str] = None

load_time class-attribute instance-attribute 

load_time: Optional[str] = None

md5 class-attribute instance-attribute 

md5: Optional[str] = None

module class-attribute instance-attribute 

module: Optional[str] = None

path class-attribute instance-attribute 

path: Optional[str] = None

sha256 class-attribute instance-attribute 

sha256: Optional[str] = None

IdaCommandOptions dataclass 

IdaCommandOptions(
    auto_analysis: bool = True,
    loading_address: Optional[int] = None,
    new_database: bool = False,
    compiler: Optional[str] = None,
    first_pass_directives: List[str] = list(),
    second_pass_directives: List[str] = list(),
    disable_fpp: bool = False,
    entry_point: Optional[int] = None,
    jit_debugger: Optional[bool] = None,
    log_file: Optional[str] = None,
    disable_mouse: bool = False,
    plugin_options: Optional[str] = None,
    output_database: Optional[str] = None,
    processor: Optional[str] = None,
    db_compression: Optional[str] = None,
    run_debugger: Optional[str] = None,
    load_resources: bool = False,
    script_file: Optional[str] = None,
    script_args: List[str] = list(),
    file_type: Optional[str] = None,
    file_member: Optional[str] = None,
    empty_database: bool = False,
    windows_dir: Optional[str] = None,
    no_segmentation: bool = False,
    debug_flags: Union[int, List[str]] = 0,
)

Configuration for building IDA command line arguments.

Set the desired options as attributes, then call build_args() to generate the command line string. Attributes correspond to IDA switches.

Example: opts = IdaCommandOptions( auto_analysis=False, processor="arm", script_file="myscript.py", script_args=["arg1", "arg2"], debug_flags=["queue", "debugger"] ) args = opts.build_args()

Attributes: auto_analysis (bool): If False, disables auto analysis (-a). Default: True (auto analysis enabled). loading_address (Optional[int]): Address (in paragraphs, 16 bytes each) to load the file at (-b). Default: None (not set). new_database (bool): If True, deletes the old database and creates a new one (-c). Default: False. compiler (Optional[str]): Compiler identifier string for the database (-C). Default: None. first_pass_directives (List[str]): Directives for first pass configuration (-d). Default: []. second_pass_directives (List[str]): Directives for second pass configuration (-D). Default: []. disable_fpp (bool): If True, disables FPP instructions (IBM PC only) (-f). Default: False. entry_point (Optional[int]): Entry point address (-i). Default: None (not set). jit_debugger (Optional[bool]): If set, enables/disables IDA as just-in-time debugger (-I). Default: None. log_file (Optional[str]): Path to the log file (-L). Default: None. disable_mouse (bool): If True, disables mouse support in text mode (-M). Default: False. plugin_options (Optional[str]): Options to pass to plugins (-O). Default: None. output_database (Optional[str]): Output database path (-o). Implies new_database. Default: None. processor (Optional[str]): Processor type identifier (-p). Default: None. db_compression (Optional[str]): Database compression ('compress', 'pack', 'no_pack') (-P). Default: None. run_debugger (Optional[str]): Debugger options string to run immediately (-r). Default: None. load_resources (bool): If True, loads MS Windows exe resources (-R). Default: False. script_file (Optional[str]): Script file to execute on database open (-S). Default: None. script_args (List[str]): Arguments to pass to the script (-S). Default: []. file_type (Optional[str]): File type prefix for input (-T). Default: None. file_member (Optional[str]): Archive member name, used with file_type (-T). Default: None. empty_database (bool): If True, creates an empty database (-t). Default: False. windows_dir (Optional[str]): MS Windows directory path (-W). Default: None. no_segmentation (bool): If True, disables segmentation (-x). Default: False. debug_flags (Union[int, List[str]]): Debug flags as integer or list of names (-z). Default: 0.

Methods:

  • build_args –

    Construct the command line arguments string from the configured options.

Attributes:

  • auto_analysis (bool) –

    If False, disables auto analysis (-a). Default: True (enabled).

  • compiler (Optional[str]) –

    Compiler identifier string for the database (-C).

  • db_compression (Optional[str]) –

    Database compression: 'compress', 'pack', or 'no_pack' (-P).

  • debug_flags (Union[int, List[str]]) –

    Debug flags as integer value or list of flag names (-z).

  • disable_fpp (bool) –

    If True, disables FPP instructions (IBM PC only) (-f).

  • disable_mouse (bool) –

    If True, disables mouse support in text mode (-M).

  • empty_database (bool) –

    If True, creates an empty database (-t).

  • entry_point (Optional[int]) –

    Entry point address (-i).

  • file_member (Optional[str]) –

    Archive member name, used with file_type (-T).

  • file_type (Optional[str]) –

    File type prefix for input (-T).

  • first_pass_directives (List[str]) –

    Directives for first pass configuration (-d).

  • jit_debugger (Optional[bool]) –

    If set, enables/disables IDA as just-in-time debugger (-I).

  • load_resources (bool) –

    If True, loads MS Windows exe resources (-R).

  • loading_address (Optional[int]) –

    Address (in paragraphs, 16 bytes each) to load the file at (-b).

  • log_file (Optional[str]) –

    Path to the log file (-L).

  • new_database (bool) –

    If True, deletes the old database and creates a new one (-c).

  • no_segmentation (bool) –

    If True, disables segmentation (-x).

  • output_database (Optional[str]) –

    Output database path (-o). Implies new_database.

  • plugin_options (Optional[str]) –

    Options to pass to plugins (-O).

  • processor (Optional[str]) –

    Processor type identifier (-p).

  • run_debugger (Optional[str]) –

    Debugger options string to run immediately (-r).

  • script_args (List[str]) –

    Arguments to pass to the script file (-S).

  • script_file (Optional[str]) –

    Script file to execute when database opens (-S).

  • second_pass_directives (List[str]) –

    Directives for second pass configuration (-D).

  • windows_dir (Optional[str]) –

    MS Windows directory path (-W).

auto_analysis class-attribute instance-attribute 

auto_analysis: bool = True

If False, disables auto analysis (-a). Default: True (enabled).

compiler class-attribute instance-attribute 

compiler: Optional[str] = None

Compiler identifier string for the database (-C).

db_compression class-attribute instance-attribute 

db_compression: Optional[str] = None

Database compression: 'compress', 'pack', or 'no_pack' (-P).

debug_flags class-attribute instance-attribute 

debug_flags: Union[int, List[str]] = 0

Debug flags as integer value or list of flag names (-z).

disable_fpp class-attribute instance-attribute 

disable_fpp: bool = False

If True, disables FPP instructions (IBM PC only) (-f).

disable_mouse class-attribute instance-attribute 

disable_mouse: bool = False

If True, disables mouse support in text mode (-M).

empty_database class-attribute instance-attribute 

empty_database: bool = False

If True, creates an empty database (-t).

entry_point class-attribute instance-attribute 

entry_point: Optional[int] = None

Entry point address (-i).

file_member class-attribute instance-attribute 

file_member: Optional[str] = None

Archive member name, used with file_type (-T).

file_type class-attribute instance-attribute 

file_type: Optional[str] = None

File type prefix for input (-T).

first_pass_directives class-attribute instance-attribute 

first_pass_directives: List[str] = field(
    default_factory=list
)

Directives for first pass configuration (-d).

jit_debugger class-attribute instance-attribute 

jit_debugger: Optional[bool] = None

If set, enables/disables IDA as just-in-time debugger (-I).

load_resources class-attribute instance-attribute 

load_resources: bool = False

If True, loads MS Windows exe resources (-R).

loading_address class-attribute instance-attribute 

loading_address: Optional[int] = None

Address (in paragraphs, 16 bytes each) to load the file at (-b).

log_file class-attribute instance-attribute 

log_file: Optional[str] = None

Path to the log file (-L).

new_database class-attribute instance-attribute 

new_database: bool = False

If True, deletes the old database and creates a new one (-c).

no_segmentation class-attribute instance-attribute 

no_segmentation: bool = False

If True, disables segmentation (-x).

output_database class-attribute instance-attribute 

output_database: Optional[str] = None

Output database path (-o). Implies new_database.

plugin_options class-attribute instance-attribute 

plugin_options: Optional[str] = None

Options to pass to plugins (-O).

processor class-attribute instance-attribute 

processor: Optional[str] = None

Processor type identifier (-p).

run_debugger class-attribute instance-attribute 

run_debugger: Optional[str] = None

Debugger options string to run immediately (-r).

script_args class-attribute instance-attribute 

script_args: List[str] = field(default_factory=list)

Arguments to pass to the script file (-S).

script_file class-attribute instance-attribute 

script_file: Optional[str] = None

Script file to execute when database opens (-S).

second_pass_directives class-attribute instance-attribute 

second_pass_directives: List[str] = field(
    default_factory=list
)

Directives for second pass configuration (-D).

windows_dir class-attribute instance-attribute 

windows_dir: Optional[str] = None

MS Windows directory path (-W).

build_args 

build_args() -> str

Construct the command line arguments string from the configured options.

Returns: str: All command line arguments for IDA, separated by spaces.