The command line

The package installs a command named asqueel. python dash m asqueel runs the same entry point. Three commands manage a local registry of configuration folders. check validates a configuration without connecting. shell opens a Python console with the database ready. db plan and db apply run the migrations of lesson 30.

A configuration folder contains a file named configure dot py. That file defines exactly one subclass of SqlDatabaseConfig. An imported recipe does not count, so this file subclasses the course recipe. The recipe uses absolute imports. Python package roots that contain the recipe are made importable while it loads. Other modules must already be importable. Here PYTHONPATH points to the folder of the course model. The course recipe reads its DSN from the variable ASQUEEL_DSN, through EnvResolver.

register stores a card under a name. The card is a JSON file in the folder databases of the asqueel home. The home is tilde slash dot asqueel, or the value of ASQUEEL_HOME. The card holds the absolute path of the folder and nothing else. No configuration value and no credential is copied. register refuses a name that already exists. list prints each name with its folder. A name uses letters, digits, underscores and hyphens.

Every command after the registry commands takes a target. A bare name means a registered card. A path with a slash means a folder or a recipe file. Write dot slash before a relative folder, because a bare name is always a card. module colon Class names an importable recipe class. Without a target, the command reads configure dot py in the current folder. dash dash config is an alternative to the positional target, and you cannot give both. check builds the model and reads the connection settings, including the resolvers. It does not connect to the database.

db plan calls db dot migration_plan and prints the commands. It changes nothing. db apply calls db dot migrate. It computes a fresh plan, applies it, prints it, and compares again. It never replays a plan printed earlier. Warnings go to standard error, each prefixed with Warning. An empty plan prints No changes.

db plan and db apply accept four flags. Each flag passes one option of lesson 30. dash dash allow dash removals enables the supported removals, which are columns. dash dash no dash foreign dash keys creates no foreign key constraint. dash dash force converts filled columns, and values that do not convert become NULL. dash dash backup does the same and keeps the old values in a backup column. On an up-to-date database, every combination prints No changes.

shell opens the standard Python console with one variable, db. db is the AsqueelDb of the target. The rules of lesson 27 apply. Leaving the console with control D calls closeConnection, which rolls back. This insert was never committed, so the table is still empty after exit.

The exit code is zero on success. It is one when the operation fails, for example an unknown card or a migration error. It is two for a syntax error on the command line. It is one hundred thirty when you interrupt the command. For unexpected errors, the command prints only the exception type. It never prints the exception text, because driver messages can contain resolved credentials. A missing import prints a message about Python dependencies. unregister removes the card only. The folder and the database stay.

The registry stores only folder paths, under the asqueel home. A target is a card name, a path or a module and class, and check never connects. db plan and db apply call the same methods as Python, with the same four options. The next lesson places asqueel databases inside a host application.