Skip to content

Backends API

Base Backend

dbcreds.backends.base.CredentialBackend

Bases: ABC

Abstract base class for credential storage backends.

All credential backends must inherit from this class and implement the required methods.

Functions

delete_credential(key: str) -> bool abstractmethod

Delete a credential from storage.

Args: key: Unique identifier for the credential

Returns: True if successful, False otherwise

Examples: >>> backend.delete_credential("dbcreds:dev")

Source code in dbcreds\backends\base.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@abstractmethod
def delete_credential(self, key: str) -> bool:
    """
    Delete a credential from storage.

    Args:
        key: Unique identifier for the credential

    Returns:
        True if successful, False otherwise

    Examples:
        >>> backend.delete_credential("dbcreds:dev")
    """
    pass

get_credential(key: str) -> Optional[Tuple[str, str, Dict[str, Any]]] abstractmethod

Retrieve a credential from storage.

Args: key: Unique identifier for the credential

Returns: Tuple of (username, password, metadata) if found, None otherwise

Examples: >>> result = backend.get_credential("dbcreds:dev") >>> if result: ... username, password, metadata = result

Source code in dbcreds\backends\base.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@abstractmethod
def get_credential(self, key: str) -> Optional[Tuple[str, str, Dict[str, Any]]]:
    """
    Retrieve a credential from storage.

    Args:
        key: Unique identifier for the credential

    Returns:
        Tuple of (username, password, metadata) if found, None otherwise

    Examples:
        >>> result = backend.get_credential("dbcreds:dev")
        >>> if result:
        ...     username, password, metadata = result
    """
    pass

is_available() -> bool abstractmethod

Check if this backend is available on the current system.

Returns: True if the backend can be used, False otherwise

Examples: >>> backend = KeyringBackend() >>> if backend.is_available(): ... print("Keyring is available")

Source code in dbcreds\backends\base.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@abstractmethod
def is_available(self) -> bool:
    """
    Check if this backend is available on the current system.

    Returns:
        True if the backend can be used, False otherwise

    Examples:
        >>> backend = KeyringBackend()
        >>> if backend.is_available():
        ...     print("Keyring is available")
    """
    pass

list_credentials() -> list[str]

List all credential keys managed by this backend.

Returns: List of credential keys

Note: This is optional and may not be implemented by all backends.

Source code in dbcreds\backends\base.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def list_credentials(self) -> list[str]:
    """
    List all credential keys managed by this backend.

    Returns:
        List of credential keys

    Note:
        This is optional and may not be implemented by all backends.
    """
    return []

set_credential(key: str, username: str, password: str, metadata: Dict[str, Any]) -> bool abstractmethod

Store a credential.

Args: key: Unique identifier for the credential username: Username to store password: Password to store metadata: Additional metadata to store

Returns: True if successful, False otherwise

Examples: >>> success = backend.set_credential( ... "dbcreds:dev", ... "myuser", ... "mypass", ... {"host": "localhost", "port": 5432} ... )

Source code in dbcreds\backends\base.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@abstractmethod
def set_credential(self, key: str, username: str, password: str, metadata: Dict[str, Any]) -> bool:
    """
    Store a credential.

    Args:
        key: Unique identifier for the credential
        username: Username to store
        password: Password to store
        metadata: Additional metadata to store

    Returns:
        True if successful, False otherwise

    Examples:
        >>> success = backend.set_credential(
        ...     "dbcreds:dev",
        ...     "myuser",
        ...     "mypass",
        ...     {"host": "localhost", "port": 5432}
        ... )
    """
    pass

Keyring Backend

dbcreds.backends.keyring.KeyringBackend

Bases: CredentialBackend

Keyring-based credential storage backend.

Uses the python-keyring library to store credentials in the system's native credential store.

Functions

delete_credential(key: str) -> bool

Delete credential from keyring.

get_credential(key: str) -> Optional[Tuple[str, str, Dict[str, Any]]]

Retrieve credential from keyring.

is_available() -> bool

Check if keyring is available and functional.

list_credentials() -> list[str]

List all dbcreds keys in keyring.

set_credential(key: str, username: str, password: str, metadata: Dict[str, Any]) -> bool

Store credential in keyring.

Windows Backend

dbcreds.backends.windows.WindowsCredentialBackend()

Bases: CredentialBackend

Windows Credential Manager backend.

Uses the Windows API to securely store credentials in the Windows Credential Manager.

Initialize Windows API functions.

Functions

delete_credential(key: str) -> bool

Delete credential from Windows Credential Manager.

get_credential(key: str) -> Optional[Tuple[str, str, Dict[str, Any]]]

Retrieve credential from Windows Credential Manager.

is_available() -> bool

Check if Windows Credential Manager is available.

set_credential(key: str, username: str, password: str, metadata: Dict[str, Any]) -> bool

Store credential in Windows Credential Manager.

Environment Backend

dbcreds.backends.environment.EnvironmentBackend

Bases: CredentialBackend

Environment variable credential backend.

Reads credentials from environment variables using a naming convention. Variables should be named as: DBCREDS_{ENV}_{FIELD}

Example: DBCREDS_DEV_HOST=localhost DBCREDS_DEV_PORT=5432 DBCREDS_DEV_USERNAME=myuser DBCREDS_DEV_PASSWORD=mypass

Functions

delete_credential(key: str) -> bool

Delete credential from environment variables.

get_credential(key: str) -> Optional[Tuple[str, str, Dict[str, Any]]]

Retrieve credential from environment variables.

is_available() -> bool

Environment variables are always available.

set_credential(key: str, username: str, password: str, metadata: Dict[str, Any]) -> bool

Set credential in environment variables.

Note: This only affects the current process and its children.

Config Backend

dbcreds.backends.config.ConfigFileBackend(config_dir: Optional[str] = None)

Bases: CredentialBackend

Configuration file backend.

Stores environment configurations and non-sensitive metadata in JSON files. This backend should not be used for storing passwords directly.

Initialize the config file backend.

Args: config_dir: Directory to store configuration files

Functions

delete_credential(key: str) -> bool

Delete credential metadata from config file.

get_credential(key: str) -> Optional[Tuple[str, str, Dict[str, Any]]]

Retrieve credential metadata from config file.

Note: This backend does not store passwords.

is_available() -> bool

Check if we can write to the config directory.

load_environments() -> List[Dict[str, Any]]

Load environment configurations.

save_environments(environments: List[Dict[str, Any]]) -> bool

Save environment configurations.

set_credential(key: str, username: str, password: str, metadata: Dict[str, Any]) -> bool

Store credential metadata in config file.

Note: Password is not stored, only metadata.