Skip to content

Commit 16407ed

Browse files
claudeclaude
committed
Rewrite README for crates.io; clarify docs.rs handling
README: - Model after Python predecessor: logo, badges (crates.io), description, install (cargo + binary download), project structure, manifest example, .iql anchor reference, accurate mermaid diagram of the 3 execution flows (createorupdate / statecheck / exports-as-proxy), usage table, link to microsite for full docs - Mermaid diagram redrawn to match actual Rust implementation: createorupdate skips all checks; statecheck triggers traditional exists→check→deploy flow; exports-only path tries exports first as a single-query fast path, falls back to exists if empty Cargo.toml: - Add [package.metadata.docs.rs] no-default-features = true; this is a binary-only crate so there is no lib API to document — crates.io renders README.md via the readme field already set; lib.rs with include_str! is not applicable here https://claude.ai/code/session_01GzGtjMcwBXyVW3uKW4F2Ai
1 parent ab809c3 commit 16407ed

2 files changed

Lines changed: 146 additions & 68 deletions

File tree

‎Cargo.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ keywords = ["stackql", "infrastructure", "iac", "cloud", "devops"]
1212
categories = ["command-line-utilities", "development-tools"]
1313
readme = "README.md"
1414

15+
# docs.rs: this is a binary-only crate — no public library API to document.
16+
# The README (above) is what crates.io renders on the package page.
17+
[package.metadata.docs.rs]
18+
no-default-features = true
19+
1520
[dependencies]
1621
clap = { version = "4.3", features = ["derive"] }
1722
colored = "2.0"

‎README.md‎

Lines changed: 141 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,183 @@
1-
# stackql-deploy
1+
<div align="center">
22

3-
[![Crates.io](https://img.shields.io/crates/v/stackql-deploy.svg)](https://crates.io/crates/stackql-deploy)
4-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3+
[![stackql-deploy logo](https://stackql.io/img/stackql-deploy-logo.png)](https://github.com/stackql/stackql)
54

6-
**stackql-deploy** is an infrastructure-as-code framework for declarative cloud resource management using [StackQL](https://stackql.io). Define your cloud resources once using StackQL queries and YAML manifests, then `build`, `test`, and `teardown` across any environment.
5+
**Model-driven resource provisioning and deployment framework using StackQL.**
76

8-
> This is the Rust rewrite (v2.x). The original Python package (`stackql-deploy` on PyPI, v1.x) is archived — see the [Python package changelog](https://github.com/stackql/stackql-deploy/blob/main/CHANGELOG.md) for prior release history.
7+
[![Crates.io](https://img.shields.io/crates/v/stackql-deploy)](https://crates.io/crates/stackql-deploy)
8+
[![Crates.io Downloads](https://img.shields.io/crates/d/stackql-deploy)](https://crates.io/crates/stackql-deploy)
9+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
10+
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-brightgreen)](https://github.com/stackql/stackql-deploy/releases)
11+
[![Docs](https://img.shields.io/badge/docs-stackql--deploy.io-brightgreen)](https://stackql-deploy.io/docs)
912

10-
---
11-
12-
## Install
13+
</div>
1314

14-
### Via `cargo`
15-
16-
```sh
17-
cargo install stackql-deploy
18-
```
15+
---
1916

20-
### Direct binary download
17+
**stackql-deploy** is a multi-cloud Infrastructure-as-Code framework inspired by [dbt](https://www.getdbt.com/), built on top of [StackQL](https://github.com/stackql/stackql). Define cloud resources as SQL-like models, then `build`, `test`, and `teardown` across any environment — no state files required.
2118

22-
Pre-built binaries for Linux (x86_64 / ARM64), macOS (Apple Silicon / Intel), and Windows (x86_64) are available on the [GitHub Releases](https://github.com/stackql/stackql-deploy/releases) page.
19+
> This is the Rust rewrite (v2.x). The original Python package (v1.x, last release 1.9.4) is now archived — see its [changelog](https://github.com/stackql/stackql-deploy/blob/main/CHANGELOG.md) for prior history.
2320
24-
**Linux / macOS:**
21+
## Install
2522

23+
**Via `cargo`:**
2624
```sh
27-
# Replace <version> and <target> as appropriate, e.g. 2.0.0 and linux-x86_64
28-
curl -L https://github.com/stackql/stackql-deploy/releases/download/v<version>/stackql-deploy-<target>.tar.gz | tar xz
29-
chmod +x stackql-deploy
30-
sudo mv stackql-deploy /usr/local/bin/
25+
cargo install stackql-deploy
3126
```
3227

33-
**Windows:**
34-
35-
Download the `.zip` from the releases page and add the extracted binary to your `PATH`.
36-
37-
---
28+
**Direct binary download** (Linux, macOS, Windows — x86\_64 and ARM64):
3829

39-
## Quick start
30+
Download the latest release from the [GitHub Releases](https://github.com/stackql/stackql-deploy/releases) page, extract, and place the binary on your `PATH`.
4031

41-
### 1. Initialise a new project
32+
## How it works
4233

43-
```sh
44-
# Using a built-in provider template
45-
stackql-deploy init my-stack --provider aws
34+
A `stackql-deploy` project is a directory with a manifest and StackQL query files:
4635

47-
# Using a template from the template hub
48-
stackql-deploy init my-stack --template google/starter
4936
```
50-
51-
### 2. Build (deploy) your stack
52-
53-
```sh
54-
stackql-deploy build my-stack dev
37+
example_stack/
38+
├── stackql_manifest.yml
39+
└── resources/
40+
└── monitor_resource_group.iql
5541
```
5642

57-
### 3. Test your stack
58-
59-
```sh
60-
stackql-deploy test my-stack dev
43+
The manifest declares providers, global variables, and resources:
44+
45+
```yaml
46+
version: 1
47+
name: example_stack
48+
description: activity monitor stack
49+
providers:
50+
- azure
51+
globals:
52+
- name: subscription_id
53+
value: "{{ vars.AZURE_SUBSCRIPTION_ID }}"
54+
- name: location
55+
value: eastus
56+
resources:
57+
- name: monitor_resource_group
58+
description: azure resource group
59+
props:
60+
- name: resource_group_name
61+
value: "activity-monitor-{{ globals.stack_env }}"
6162
```
6263
63-
### 4. Tear down your stack
64+
> Use `stackql-deploy init example_stack --provider azure` to scaffold a new project.
65+
66+
Resource `.iql` files define mutation and check queries using SQL anchors:
67+
68+
```sql
69+
/*+ create */
70+
INSERT INTO azure.resources.resource_groups(
71+
resourceGroupName, subscriptionId, data__location
72+
)
73+
SELECT '{{ resource_group_name }}', '{{ subscription_id }}', '{{ location }}'
74+
75+
/*+ update */
76+
UPDATE azure.resources.resource_groups
77+
SET data__location = '{{ location }}'
78+
WHERE resourceGroupName = '{{ resource_group_name }}'
79+
AND subscriptionId = '{{ subscription_id }}'
80+
81+
/*+ delete */
82+
DELETE FROM azure.resources.resource_groups
83+
WHERE resourceGroupName = '{{ resource_group_name }}'
84+
AND subscriptionId = '{{ subscription_id }}'
85+
86+
/*+ exists */
87+
SELECT COUNT(*) as count FROM azure.resources.resource_groups
88+
WHERE subscriptionId = '{{ subscription_id }}'
89+
AND resourceGroupName = '{{ resource_group_name }}'
90+
91+
/*+ statecheck, retries=5, retry_delay=5 */
92+
SELECT COUNT(*) as count FROM azure.resources.resource_groups
93+
WHERE subscriptionId = '{{ subscription_id }}'
94+
AND resourceGroupName = '{{ resource_group_name }}'
95+
AND location = '{{ location }}'
96+
AND JSON_EXTRACT(properties, '$.provisioningState') = 'Succeeded'
97+
98+
/*+ exports */
99+
SELECT resourceGroupName, location
100+
FROM azure.resources.resource_groups
101+
WHERE subscriptionId = '{{ subscription_id }}'
102+
AND resourceGroupName = '{{ resource_group_name }}'
103+
```
64104

65-
```sh
66-
stackql-deploy teardown my-stack dev
105+
### Query execution strategy
106+
107+
For each resource, `stackql-deploy` selects an execution path based on which anchors are defined in the `.iql` file:
108+
109+
```mermaid
110+
graph TB
111+
A[resource] --> B{has\ncreateorupdate?}
112+
B -- Yes --> C[run createorupdate\nskip all checks]
113+
B -- No --> D{has statecheck?}
114+
115+
D -- Yes --> E[exists check]
116+
E --> F{exists?}
117+
F -- No --> G[create]
118+
F -- Yes --> H[statecheck]
119+
H --> I{correct\nstate?}
120+
I -- Yes --> J[✅ up to date]
121+
I -- No --> K[update]
122+
G & K --> L[post-deploy exports]
123+
124+
D -- No --> M{has exports?}
125+
M -- Yes --> N[⚡ try exports first]
126+
N --> O{returned\ndata?}
127+
O -- Yes --> P[✅ validated +\nexports captured\nin 1 query]
128+
O -- No --> Q[exists check]
129+
Q --> R{exists?}
130+
R -- No --> S[create]
131+
R -- Yes --> S2[update]
132+
S & S2 --> T[exports]
133+
M -- No --> U[exists check\ncreate or update]
67134
```
68135

69-
### Other commands
136+
**Tip:** when there is no `statecheck`, an `exports` query that selects from the live resource serves as both a validation and data-extraction step in a single API call.
137+
138+
## Usage
70139

71140
```sh
72-
# Show version / provider info
73-
stackql-deploy info
141+
# Preview what would change (no mutations)
142+
stackql-deploy build example_stack dev --dry-run
74143
75-
# Interactive StackQL shell
76-
stackql-deploy shell
144+
# Deploy
145+
stackql-deploy build example_stack dev -e AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
77146
78-
# Update the embedded StackQL binary
79-
stackql-deploy upgrade
147+
# Run checks only
148+
stackql-deploy test example_stack dev
80149
81-
# Preview what build would do (no changes applied)
82-
stackql-deploy build my-stack dev --dry-run
150+
# Deprovision (reverse order)
151+
stackql-deploy teardown example_stack dev
83152
```
84153

85-
---
154+
Common flags:
86155

87-
## Project structure
156+
| Flag | Description |
157+
|---|---|
158+
| `--dry-run` | Print queries, make no changes |
159+
| `--on-failure=rollback` | `rollback`, `ignore`, or `error` (default) |
160+
| `--env-file=.env` | Load environment variables from a file |
161+
| `-e KEY=value` | Pass individual environment variables |
162+
| `--log-level` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
163+
| `--show-queries` | Print rendered SQL before execution |
88164

89-
A `stackql-deploy` project consists of a manifest file and one or more StackQL query files:
165+
Show environment and provider info:
90166

167+
```sh
168+
stackql-deploy info
91169
```
92-
my-stack/
93-
├── stackql_manifest.yml # Declares resources, providers, and environment config
94-
└── resources/
95-
└── my_bucket.iql # StackQL queries for create/exists/state checks
96-
```
97-
98-
See the [documentation site](https://stackql.io/docs/stackql-deploy) for the full manifest reference and query file format.
99170

100-
---
171+
Full command reference:
101172

102-
## Supported providers
173+
```sh
174+
stackql-deploy --help
175+
```
103176

104-
stackql-deploy works with any provider supported by StackQL, including AWS, Google Cloud, Azure, Databricks, Snowflake, and more. See [registry.stackql.io](https://registry.stackql.io) for the full provider list.
177+
## Documentation
105178

106-
---
179+
Full documentation — manifest reference, query anchors, template filters, provider examples — is at **[stackql-deploy.io/docs](https://stackql-deploy.io/docs)**.
107180

108181
## License
109182

110-
MIT — see [LICENSE](LICENSE) for details.
183+
MIT — see [LICENSE](LICENSE).

0 commit comments

Comments
 (0)