diff --git a/README.md b/README.md index 000d79a..6d00134 100644 --- a/README.md +++ b/README.md @@ -94,17 +94,19 @@ ## Usage -Currently, sprocketship expects a `.sprocketship.yml` file and a `procedures/` directory at the same level in a directory structure. +### Structure + +Currently, sprocketship expects a `.sprocketship.yml` file in a `procedures/` directory. ``` ├── dbt_models │ ├── customers.sql │ ├── products.sql ├── procedures -│ ├── admin +│ ├── useradmin │ │ ├── create_database_writer_role.js │ │ ├── create_database_reader_role.js -│ ├── development +│ ├── sysadmin │ │ ├── create_temp_database.js └── .sprocketship.yml ``` @@ -131,6 +133,52 @@ procedures: ... ``` +### Directory-level Default Parameters + +sprocketship allows providing default parameters at any given level of +your project. These defaults will be applied recursively to any procedures +defined in any of the subdirectories, unless overridden by a default in one +of the subdirectories. + +``` +procedures: + # for all procedures, default to the below database and schema + +database: !env_var SNOWFLAKE_DATABASE + +schema: !env_var SNOWFLAKE_SCHEMA + development: + # for all procedures in the development directory, + # default to using the sysadmin role + +use_role: sysadmin + create_temp_database: + args: + - name: Name of argument + type: Type of argument + default: (Optional) default value for the argument + returns: varchar +``` + +### File Frontmatter + +Thanks to ABSQL, sprocketship also provides the ability to define parameters using file frontmatter. Suppose we have a file `create_database_writer_role.js`, we can define parameters for the stored procedure within the file using frontmatter: + +```js +/* +database: my_database +schema: my_schema +language: javascript +execute_as: owner +use_role: sysadmin +*/ +``` + +sprocketship will automatically parse and apply the parameters defined in the frontmatter to the stored procedure. + +### Recommended Configuration + +When setting up your sprocketship project, we recommend setting more general parameters (e.g., database, schema, language, etc.) in the `.sprocketship.yml` file, and anything that's specific to a given procedure should be defined in the file frontmatter of that procedure, such as the args or return type. + +### Execution + From here, simply run `$ sprocketship liftoff` @@ -140,16 +188,16 @@ from the project directory (or provide the directory, e.g. `sprocketship liftoff ### Exhaustive Options for Stored Procedure Configuration ``` -name: The name of the procedure database: The name of the database where the procedure will be stored schema: The name of the schema where the procedure will be stored language: The language of the procedure definition execute_as: caller or owner +use_role: The role you'd like to own the procedure args: - name: Name of argument type: Type of argument default: (Optional) default value for the argument -returns: The return type +returns: The return type, this can include the `NOT NULL` option comment: Explanation of the procedure ``` @@ -157,7 +205,6 @@ comment: Explanation of the procedure sprocketship currently only supports Javascript-based stored procedures (Python support coming soon!). Additionally, there are a few options from the `CREATE STORED PROCEDURE` function that are not yet supported: -* `RETURNS NOT NULL` * `CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT }` * `VOLATILE | IMMUTABLE` (deprecated) diff --git a/pyproject.toml b/pyproject.toml index 1a9b377..3ff5cf7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "sprocketship" -version = "1.0.0" +version = "1.0.1" authors = [ { name="Nicklaus Roach", email="nicklausroach@gmail.com" }, ] diff --git a/sprocketship/cli.py b/sprocketship/cli.py index 9645dab..bdd494d 100644 --- a/sprocketship/cli.py +++ b/sprocketship/cli.py @@ -26,7 +26,7 @@ def main(ctx): def liftoff(dir, show): click.echo(click.style(f"🚀 Sprocketship lifting off!", fg="white", bold=True)) data = render_file( - os.path.join(dir, "procedures", ".sprocketship.yml"), return_dict=True + os.path.join(dir, ".sprocketship.yml"), return_dict=True ) con = connector.connect(**data["snowflake"]) files = list(Path(dir).rglob("*.js")) @@ -74,7 +74,7 @@ def build(dir, target): Path(os.path.join(dir, target)).mkdir(parents=True, exist_ok=True) data = render_file( - os.path.join(dir, "procedures", ".sprocketship.yml"), return_dict=True + os.path.join(dir, ".sprocketship.yml"), return_dict=True ) files = list(Path(dir).rglob("*.js")) diff --git a/sprocketship/utils.py b/sprocketship/utils.py index 0f69d85..185a3be 100644 --- a/sprocketship/utils.py +++ b/sprocketship/utils.py @@ -18,7 +18,8 @@ def extract_configs(data, path=""): def get_file_config(path: Path, config: dict, dir: str): filename = path.stem - keys = str(path.relative_to(dir)).split("/")[:-1] + [filename] + keys = ["procedures"] + str(path.relative_to(dir)).split("/")[:-1] + [filename] + print(keys) file_config = {"path": str(path), "name": filename} curr_config = config