Database Commands¶

Commands for initializing, migrating, and managing the Faraday PostgreSQL database.

initdb¶

Initialize the Faraday database. This command creates the PostgreSQL role, database, tables, default roles/permissions, notification configuration, and the initial admin user.

This command should only be run once during initial Faraday installation.

faraday-manage initdb [OPTIONS]

Options¶

Option	Type	Default	Description
`--choose-password`	Flag	`false`	Interactively prompt for the admin user password instead of generating a random one
`--password`	String	(random)	Specify the admin user password directly (non-interactive)

Behavior¶

Checks for existing database configuration in server.ini; if found, asks whether to reconfigure
Creates a PostgreSQL role (faraday_postgresql by default, override with FARADAY_DATABASE_USER env var)
Creates a database (faraday by default, override with FARADAY_DATABASE_NAME env var)
Saves the connection string to server.ini
Creates all database tables and stamps the Alembic migration revision to head
Creates default roles and permissions
Sets up initial notification subscriptions and event types
Creates the admin user (username: faraday) with the specified or generated password

Examples¶

# Standard installation (generates random password)
faraday-manage initdb

# Choose your own password interactively
faraday-manage initdb --choose-password

# Specify password non-interactively (useful for automation)
faraday-manage initdb --password "MySecurePassword123"

# Use custom database name and user via environment variables
FARADAY_DATABASE_NAME=faraday_prod FARADAY_DATABASE_USER=faraday_app faraday-manage initdb

Output¶

On success, the command prints the admin credentials:

Admin user created with

username: faraday
password: <generated-or-chosen-password>

Danger

Warning: Do not lose the password printed on screen. It is required to log into Faraday. If lost, use faraday-manage change-password to reset it.

Common Errors¶

Error	Cause	Solution
`unknown user: postgres`	PostgreSQL not installed	Install the `postgresql` package
`could not connect to server`	PostgreSQL not running	Start PostgreSQL on port 5432
`role "faraday_postgresql" already exists`	Previous installation exists	The command will attempt to reuse existing credentials
Re-running `initdb` on existing database	Tables already exist	Use `faraday-manage migrate` instead

create-tables¶

Manually create database tables. Useful as a recovery step if initdb partially failed, or when setting up a database that already has a PostgreSQL role and database configured.

faraday-manage create-tables

Options¶

None.

Behavior¶

Reads the connection string from server.ini
Checks if alembic_version table exists (indicating tables already exist)
If tables don't exist: creates all tables and stamps the Alembic revision to head
If tables already exist: prints a message and exits without changes

Examples¶

faraday-manage create-tables

Output¶

Tables created successfully!

Or, if tables already exist:

Faraday tables already exist in the database. No tables will be created.
If you want to upgrade the schema to the latest version, you should run "faraday-manage migrate".

Common Errors¶

Error	Cause	Solution
No database configuration found	`server.ini` missing or misconfigured	Run `faraday-manage initdb` for first-time setup, or manually configure `[database]` section
`could not connect to server`	PostgreSQL not running	Start PostgreSQL service
`password authentication failed`	Wrong credentials in `server.ini`	Update the connection string in `server.ini`

migrate¶

Run Alembic database schema migrations. Upgrades the schema to the latest version by default, or downgrades to a specific revision.

faraday-manage migrate [OPTIONS] [REVISION]

Options¶

Option	Type	Default	Description
`--downgrade`	Flag	`false`	Perform a downgrade instead of an upgrade

Arguments¶

Argument	Required	Default	Description
`REVISION`	No	`head` (upgrade) / `-1` (downgrade)	Target Alembic revision identifier

Behavior¶

Upgrade (default): Applies all pending migrations up to head (or the specified revision)
Downgrade: Reverts the most recent migration (-1) or reverts to a specific revision

Examples¶

# Upgrade to the latest schema version
faraday-manage migrate

# Upgrade to a specific revision
faraday-manage migrate abc123def456

# Downgrade one revision
faraday-manage migrate --downgrade

# Downgrade to a specific revision
faraday-manage migrate --downgrade abc123def456

Common Errors¶

Error	Cause	Solution
`Migration Error` + OperationalError	Database connection issue	Check `server.ini` and PostgreSQL HBA configuration
`Migration failed!`	Migration script error	Check the specific error message; may need manual database intervention

database-schema¶

Generate PNG image files visualizing the Faraday database model. Creates two diagrams: - entity_dbschema.png — Entity-relationship diagram - uml_schema.png — UML class diagram

faraday-manage database-schema

Options¶

None.

Prerequisites¶

Requires the sqlalchemy_schemadisplay Python package and the dot (Graphviz) system utility:

pip install sqlalchemy_schemadisplay
sudo apt install xdot    # Debian/Ubuntu
brew install graphviz     # macOS

Examples¶

faraday-manage database-schema
# Output files: entity_dbschema.png, uml_schema.png (in current directory)

Output¶

Graph written to file uml_schema.png

sql-shell¶

Open an interactive PostgreSQL shell (via pgcli) connected to the Faraday database using the connection string from server.ini.

faraday-manage sql-shell

Options¶

None.

Behavior¶

Launches pgcli (a PostgreSQL CLI with auto-completion and syntax highlighting) configured with the username, password, hostname, and database name from the Faraday configuration.

Examples¶

faraday-manage sql-shell
# Opens an interactive pgcli session
# Type SQL queries directly, e.g.:
# SELECT count(*) FROM vulnerability;
# \q to exit

Prerequisites¶

The pgcli Python package must be installed (included in Faraday's dependencies).