The bot’s database

class sopel.db.SopelDB(config)

Availability: 5.0+

This defines an interface for basic, common operations on a sqlite database. It simplifies those common operations, and allows direct access to the database, wherever the user has configured it to be.

When configured with a relative filename, it is assumed to be in the same directory as the config.

alias_nick(nick, alias)

Create an alias for a nick.

Raises ValueError if the alias already exists. If nick does not already exist, it will be added along with the alias.


Return a raw database connection object.


Removes a nickname, and all associated aliases and settings.

execute(*args, **kwargs)

Execute an arbitrary SQL query against the database.

Returns a cursor object, on which things like .fetchall() can be called per PEP 249.

get_channel_value(channel, key)

Retrieves the value for a given key associated with a channel.

get_nick_id(nick, create=True)

Return the internal identifier for a given nick.

This identifier is unique to a user, and shared across all of that user’s aliases. If create is True, a new ID will be created if one does not already exist

get_nick_or_channel_value(name, key)

Gets the value key associated to the nick or channel name.

get_nick_value(nick, key)

Retrieves the value for a given key associated with a nick.

get_preferred_value(names, key)

Gets the value for the first name which has it set.

names is a list of channel and/or user names. Returns None if none of the names have the key set.


Returns a URL for the database, usable to connect with SQLAlchemy.

merge_nick_groups(first_nick, second_nick)

Merges the nick groups for the specified nicks.

Takes two nicks, which may or may not be registered. Unregistered nicks will be registered. Keys which are set for only one of the given nicks will be preserved. Where multiple nicks have values for a given key, the value set for the first nick will be used.

Note that merging of data only applies to the native key-value store. If modules define their own tables which rely on the nick table, they will need to have their merging done separately.

set_channel_value(channel, key, value)

Sets the value for a given key to be associated with the channel.

set_nick_value(nick, key, value)

Sets the value for a given key to be associated with the nick.


Removes an alias.

Raises ValueError if there is not at least one other nick in the group. To delete an entire group, use delete_group.


alias of builtins.str


alias of builtins.str