Skip to content

Commit 1c28e5b

Browse files
eric-schneidereric-schneider
authored
DOC-5432: Pre-1.0 upgrade guide (#32)
1 parent 7ac4791 commit 1c28e5b

5 files changed

Lines changed: 299 additions & 15 deletions

File tree

‎modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
* xref:install.adoc[]
33
* xref:manage-cli.adoc[]
44
* xref:upgrade.adoc[]
5+
* xref:upgrade-pre-1.0.adoc[]
56
* xref:uninstall.adoc[]
67
78
.Quickstarts

‎modules/ROOT/pages/manage-cli.adoc‎

Lines changed: 233 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -544,29 +544,250 @@ The {product} stores installation and configuration files in the following locat
544544

545545
[cols="1h,2"]
546546
|===
547-
|File / Directory |Description
547+
|File / Folder |Description
548548

549549
|`.astra`
550-
a|The `ASTRA_HOME` directory.
550+
a|The {product} home folder (`ASTRA_HOME`).
551551

552-
_Default location_: `~/.astra` (macOS and Linux), `%USERPROFILE%\.astra` (Windows)
552+
_Default location_:
553553

554-
The {product} stores the following items in this directory:
554+
* macOS and Linux: `~/.astra`
555+
* Windows: `%USERPROFILE%\.astra`
556+
* All platforms: If the `XDG_DATA_HOME` environment variable is set, then the default location is `$XDG_DATA_HOME/astra`.
555557

556-
* The {product} executable (scripted installations only)
557-
* Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]`
558-
* {scb-brief}s
558+
The {product} home folder contains the following items:
559+
560+
* The `astra` executable (scripted installations only)
561+
* Accessory executables that are downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]`
562+
* xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb-brief}s]
559563
* Cache files for <<command-auto-completion,command auto-completion>>
560564
* Logs
561565

562-
For more information about the `ASTRA_HOME` directory, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[README].
566+
For more information about `ASTRA_HOME`, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} README].
563567

564568
|`.astrarc`
565-
|The {product} configuration file.
569+
a|The {product} configuration file.
570+
571+
_Default location_:
566572

567-
_Default location_: `~/.astrarc` (macOS and Linux), `%USERPROFILE%\.astrarc` (Windows)
573+
* macOS and Linux: `~/.astrarc`
574+
* Windows: `%USERPROFILE%\.astrarc`
575+
* All platforms: If the `XDG_CONFIG_HOME` environment variable is set, then the default location is `$XDG_CONFIG_HOME/astra/.astrarc`.
568576

569-
This file stores your <<manage-configuration-profiles,configuration profiles>> and their associated application tokens.
577+
The {product} uses this file to store your <<manage-configuration-profiles,configuration profiles>> and their associated application tokens.
570578

571-
For more information about the {product} configuration file, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[README].
579+
For more information about the {product} configuration file, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[{product} README].
572580
|===
581+
582+
=== Override the default home folder location
583+
584+
You can override the default location of the {product} home folder (`.astra`) by setting the `ASTRA_HOME` environment variable.
585+
586+
[tabs]
587+
======
588+
Set the environment variable dynamically::
589+
+
590+
--
591+
Add the following line to your shell profile:
592+
593+
[source,bash,subs="+quotes"]
594+
----
595+
eval "$(astra shellenv --home "**HOME_FOLDER_PATH**")"
596+
----
597+
598+
Replace `**HOME_FOLDER_PATH**` with the full path to your preferred {product} home folder.
599+
--
600+
601+
Set the environment variable directly::
602+
+
603+
--
604+
Add the following line to your shell profile:
605+
606+
[source,bash,subs="+quotes"]
607+
----
608+
export ASTRA_HOME=**HOME_FOLDER_PATH**
609+
----
610+
611+
Replace `**HOME_FOLDER_PATH**` with the full path to your preferred {product} home folder.
612+
--
613+
======
614+
615+
=== Override the default configuration file location
616+
617+
You can override the default location of the {product} configuration file (`.astrarc`) by setting the `ASTRA_CONFIG_FILE` environment variable.
618+
619+
[tabs]
620+
======
621+
Set the environment variable dynamically::
622+
+
623+
--
624+
Add the following line to your shell profile:
625+
626+
[source,bash,subs="+quotes"]
627+
----
628+
eval "$(astra shellenv --rc "**CONFIG_FILE_PATH**/.astrarc")"
629+
----
630+
631+
Replace `**CONFIG_FILE_PATH**` with the full path to your preferred `.astrarc` configuration file.
632+
--
633+
634+
Set the environment variable directly::
635+
+
636+
--
637+
Add the following line to your shell profile:
638+
639+
[source,bash,subs="+quotes"]
640+
----
641+
export ASTRARC=**CONFIG_FILE_PATH**/.astrarc
642+
----
643+
644+
Replace `**CONFIG_FILE_PATH**` with the full path to your preferred `.astrarc` configuration file.
645+
--
646+
======
647+
648+
[#command-output]
649+
== Command output formats and exit codes
650+
651+
Most commands support the `-o` / `--output` option to specify the format of the command output:
652+
653+
[source,shell,subs="+quotes"]
654+
----
655+
astra COMMAND -o **FORMAT**
656+
----
657+
658+
The following output formats are available:
659+
660+
* `human` (default): Human-readable format, optimized for command-line readability.
661+
* `json`: Structured JSON format, suitable for programmatic parsing.
662+
* `csv`: Comma-separated output format, ideal for data export and analysis.
663+
664+
[tabs]
665+
======
666+
Human-readable::
667+
+
668+
--
669+
The human-readable format uses tables, lists, and other visual elements to present information on the command line.
670+
--
671+
672+
JSON::
673+
+
674+
--
675+
Every command supporting JSON output will always return a response of exactly this schema:
676+
677+
.JSON output schema
678+
[source,json]
679+
----
680+
{
681+
"code": "OK" | "UNCAUGHT" | "DATABASE_NOT_FOUND" | "...",
682+
"message": "Optional human-readable description",
683+
"data": {
684+
// Command-specific payload, may be an object, array, or primitive
685+
},
686+
"nextSteps": [
687+
{
688+
"command": "astra ...",
689+
"comment": "Explanation of why/when to run this next"
690+
}
691+
]
692+
}
693+
----
694+
695+
All field names in the JSON output are in camel case (`fieldName`).
696+
697+
[cols="1,1,2"]
698+
|===
699+
|Name |Type |Summary
700+
701+
|`code`
702+
|`string`
703+
a|A string enum representing the exit code of the command.
704+
705+
Common values include:
706+
707+
* `OK`: command succeeded
708+
* `UNCAUGHT`: unexpected failure
709+
* `DATABASE_NOT_FOUND`: referenced resource missing
710+
* Other command-specific codes
711+
712+
|`message`
713+
|`string`
714+
|Optional.
715+
A human-friendly message describing the result or error of the command.
716+
717+
Not all commands include a message.
718+
719+
|`data`
720+
|Any (type varies by command)
721+
|Freeform data specific to the command.
722+
Typically an object or array, but may be a primitive value (string, number, boolean, etc.) depending on the command.
723+
724+
|`nextSteps`
725+
|`array` or `null`
726+
a|Optional.
727+
Only present if there are actionable next steps that you can take (it will never be an empty list).
728+
729+
If present, it is an array of recommended next-step objects containing the following fields:
730+
731+
* `command`: The command to run.
732+
* `comment`: An explanation of why/when to run this next.
733+
|===
734+
--
735+
736+
CSV::
737+
+
738+
--
739+
Every command supporting CSV output will always return an RFC-4180-compliant response of exactly this schema:
740+
741+
.CSV output schema
742+
[source,csv]
743+
----
744+
code,message,data_field_1,data_field_2,...
745+
----
746+
747+
All field names in the CSV output are in snake case (`field_name`).
748+
749+
The first row is always the header, defining the column names.
750+
Each subsequent row represents one data record from the command.
751+
752+
The `code` and `message` fields may repeat for each row of data to keep the CSV schema consistent.
753+
Values may contain commas or newlines and be wrapped in quotes to ensure RFC-4180-compliant CSV output.
754+
755+
[cols="1,1,2"]
756+
|===
757+
|Name |Type |Summary
758+
759+
|`code`
760+
|`string`
761+
a|A string enum representing the exit code of the command.
762+
763+
Common values include:
764+
765+
* `OK`: command succeeded
766+
* `UNCAUGHT`: unexpected failure
767+
* `DATABASE_NOT_FOUND`: referenced resource missing
768+
* Other command-specific codes
769+
770+
If no rows are returned, you should assume an implicit `OK` code.
771+
772+
|`message`
773+
|`string`
774+
|Optional.
775+
A human-friendly message describing the result or error of the command.
776+
777+
Not all commands include a message, and this field will be empty if there is nothing to report.
778+
779+
|Additional data fields
780+
|Any (type varies by command)
781+
a|Command-specific fields representing the actual data returned.
782+
783+
Fields may be empty if there is nothing to report.
784+
785+
Column order is consistent per command.
786+
|===
787+
--
788+
======
789+
790+
[NOTE]
791+
====
792+
For commands that issue GET requests, the `json` response generally contains the raw response from the server, whereas the `human` and `csv` formats contain a simplified version of the data.
793+
====

‎modules/ROOT/pages/uninstall.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ Manual removal::
9999
rm $(astra config path -p)
100100
----
101101
102-
. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]:
102+
. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home folder]:
103103
+
104104
[source,shell]
105105
----
@@ -229,7 +229,7 @@ Manual removal::
229229
rm -f $(astra config path -p)
230230
----
231231
232-
. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]:
232+
. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home folder]:
233233
+
234234
[source,powershell]
235235
----
@@ -251,7 +251,7 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul
251251
Homebrew::
252252
+
253253
--
254-
. Delete the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`):
254+
. Delete the {product} home folder (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`):
255255
+
256256
.. Run the `xref:commands:astra-nuke.adoc[]` command:
257257
+

‎modules/ROOT/pages/upgrade-pre-1.0.adoc‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
= Upgrade from pre-1.0 versions of the {product}
2+
:navtitle: Upgrade from pre-1.0 versions
3+
4+
// Author's note: Once we get further away from the 1.0 release, we can probably move the content of this page into a section of on the main upgrade.adoc page.
5+
6+
{product} 1.0 and later do not support xref:ROOT:upgrade.adoc[in-place upgrades] from versions earlier than 1.0.
7+
8+
If you have an earlier version installed, you must delete the `astra` executable before you can install the latest version:
9+
10+
[tabs,sync-group-id=platforms]
11+
======
12+
macOS and Linux::
13+
+
14+
--
15+
[source,shell]
16+
----
17+
rm ~/.astra/cli/astra
18+
----
19+
20+
.Delete custom installation
21+
[%collapsible]
22+
====
23+
If you installed the {product} to a custom location, you can use the following command to delete the `astra` executable if it exists in your PATH:
24+
25+
[source,shell]
26+
----
27+
rm $(which astra)
28+
----
29+
====
30+
31+
This command does not delete your xref:ROOT:manage-cli.adoc#file-locations[{product} home folder and configuration file] (`.astra` and `.astrarc`).
32+
Leave these files in place so that the new version of the {product} can continue to connect using your existing configuration.
33+
--
34+
35+
Homebrew::
36+
+
37+
--
38+
[source,shell]
39+
----
40+
brew uninstall datastax/astra-cli/astra-cli
41+
----
42+
43+
Uninstalling with Homebrew does not delete your xref:ROOT:manage-cli.adoc#file-locations[{product} home folder and configuration file] (`.astra` and `.astrarc`).
44+
Leave these files in place so that the new version of the {product} can continue to connect using your existing configuration.
45+
--
46+
======
47+
48+
After you delete the old `astra` executable, follow the instructions in xref:ROOT:install.adoc[] to install the latest version.
49+
50+
.Breaking changes in version 1.0
51+
[IMPORTANT]
52+
====
53+
{product} version 1.0 is largely backwards-compatible with pre-1.0 versions.
54+
However, there are some changes that might break certain scripted usage, such as:
55+
56+
* New standardized xref:ROOT:manage-cli.adoc#output-formats[JSON and CSV output formats and exit codes].
57+
58+
* Minor command and flag name changes.
59+
For a full list of name changes, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#whats-changed[release notes].
60+
====

‎modules/ROOT/pages/upgrade.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33

44
Keep the {product} up to date to access new features, improvements, and security updates.
55

6+
If you're upgrading from version 0.6 or earlier, see xref:ROOT:upgrade-pre-1.0.adoc[].
7+
68
[IMPORTANT]
79
====
810
If you used a package manager to install the {product}, such as Homebrew, then you must use the same package manager to upgrade the {product}.

0 commit comments

Comments
 (0)