cradle-sql

Rebuild the database schema

$ cradle sql build

$ cradle sql build [package]

$ cradle sql flush

$ cradle sql flush [package]

$ cradle sql populate

$ cradle sql populate [package]

cradle-sql [OPTIONS] [SQL_FILE]

--db DB_URL
    
Specifies the database connection URL. This overrides any database configuration found in the cradle project's settings.

--sql SQL_STRING
    
Executes the provided SQL string directly, instead of reading from a file.

--dry-run
    
Prints the SQL that would be executed without actually running it against the database. Useful for verification.

--output FILE
    
Redirects the output of the command (e.g., query results or messages) to a specified file.

--help
    
Displays a help message and exits.

SQL_FILE
    
The path to a SQL file containing statements to be executed. If not provided, and --sql is not used, cradle-sql may expect input from standard input or simply do nothing.

cradle-sql is an executable command provided by the cradle project, a lightweight tool designed for managing database schema migrations. Unlike a general-purpose SQL client, cradle-sql is specifically intended to execute SQL scripts against a database configured within the cradle environment.

It allows developers to run arbitrary SQL statements or migration scripts, often as part of a development workflow or to apply a specific schema change. It can accept SQL directly via the command line or from a specified file. The command integrates with cradle's database connection settings, but also allows overriding them. It's particularly useful for applying atomic SQL changes or troubleshooting migrations managed by cradle.

• cradle-sql requires a properly configured cradle project or an explicit database connection URL via --db. Without it, it cannot connect to a database.
• It executes SQL directly; therefore, care must be taken with the SQL content to avoid unintended data loss or corruption, especially in production environments.
• Error handling for complex SQL scripts might be basic, relying on the underlying database engine's error reporting.
• This command is part of the cradle Python package and might not be globally available if cradle is installed in a virtual environment without being linked to the system's PATH.

While cradle-sql can execute arbitrary SQL, its primary context is within a cradle project. It often relies on the database connection information defined in the project's cradle configuration file, simplifying database interactions for migration-related tasks.

Executing arbitrary SQL from files or command-line arguments can pose security risks if the SQL source is untrusted or contains malicious statements. Users should ensure the integrity and safety of the SQL content before execution.

The cradle project, and by extension cradle-sql, emerged as a lightweight alternative for managing database schema changes, focusing on simplicity and ease of use, particularly within Python ecosystems. Its development history is tied to the need for a less opinionated and more flexible migration tool compared to some existing, more complex frameworks. cradle-sql specifically serves as a utility for direct SQL execution within the cradle framework, complementing its migration capabilities by allowing ad-hoc or post-migration SQL operations.

cradle(1), psql(1), mysql(1), sqlite3(1)