@@ -58,12 +58,51 @@ export class AstraDbAdmin extends DbAdmin {
5858 }
5959
6060 /**
61+ * Gets the ID of the Astra DB instance this object is managing.
62+ *
63+ * @returns the ID of the Astra DB instance.
64+ */
65+ public get id ( ) : string {
66+ return this . _db . id ;
67+ }
68+
69+ /**
70+ * Gets the underlying `Db` object. The options for the db were set when the AstraDbAdmin instance, or whatever
71+ * spawned it, was created.
72+ *
73+ * @example
74+ * ```typescript
75+ * const dbAdmin = client.admin().dbAdmin('<endpoint>', {
76+ * namespace: 'my-namespace',
77+ * useHttp2: false,
78+ * });
79+ *
80+ * const db = dbAdmin.db();
81+ * console.log(db.id);
82+ * ```
83+ *
6184 * @returns the underlying `Db` object.
6285 */
6386 public override db ( ) : Db {
6487 return this . _db ;
6588 }
6689
90+ /**
91+ * Fetches the complete information about the database, such as the database name, IDs, region, status, actions, and
92+ * other metadata.
93+ *
94+ * The method issues a request to the DevOps API each time it is invoked, without caching mechanisms;
95+ * this ensures up-to-date information for usages such as real-time collection validation by the application.
96+ *
97+ *
98+ * @example
99+ * ```typescript
100+ * const info = await dbAdmin.info();
101+ * console.log(info.info.name, info.creationTime);
102+ * ```
103+ *
104+ * @returns A promise that resolves to the complete database information.
105+ */
67106 public async info ( ) : Promise < FullDatabaseInfo > {
68107 const resp = await this . _httpClient . request ( {
69108 method : HTTP_METHODS . Get ,
@@ -72,10 +111,56 @@ export class AstraDbAdmin extends DbAdmin {
72111 return resp . data ;
73112 }
74113
114+ /**
115+ * Lists the namespaces in the database.
116+ *
117+ * The first element in the returned array is the default namespace of the database, and the rest are additional
118+ * namespaces in no particular order.
119+ *
120+ * @example
121+ * ```typescript
122+ * const namespaces = await dbAdmin.listNamespaces();
123+ *
124+ * // ['default_keyspace', 'my_other_keyspace']
125+ * console.log(namespaces);
126+ * ```
127+ *
128+ * @returns A promise that resolves to an array of namespace names.
129+ */
75130 public override async listNamespaces ( ) : Promise < string [ ] > {
76131 return this . info ( ) . then ( i => [ i . info . keyspace ! , ...i . info . additionalKeyspaces ?? [ ] ] . filter ( Boolean ) )
77132 }
78133
134+ /**
135+ * Creates a new, additional, namespace (aka keyspace) for this database.
136+ *
137+ * **NB. this is a "long-running" operation. See {@link AdminBlockingOptions} about such blocking operations.** The
138+ * default polling interval is 2 seconds. Expect it to take roughly 8-10 seconds to complete.
139+ *
140+ * @example
141+ * ```typescript
142+ * await dbAdmin.createNamespace('my_other_keyspace1');
143+ *
144+ * // ['default_keyspace', 'my_other_keyspace1']
145+ * console.log(await dbAdmin.listNamespaces());
146+ *
147+ * await dbAdmin.createNamespace('my_other_keyspace2', {
148+ * blocking: false,
149+ * });
150+ *
151+ * // Will not include 'my_other_keyspace2' until the operation completes
152+ * console.log(await dbAdmin.listNamespaces());
153+ * ```
154+ *
155+ * @remarks
156+ * Note that if you choose not to block, the created namespace object will not be able to be used until the
157+ * operation completes, which is up to the caller to determine.
158+ *
159+ * @param namespace - The name of the new namespace.
160+ * @param options - The options for the blocking behavior of the operation.
161+ *
162+ * @returns A promise that resolves when the operation completes.
163+ */
79164 public override async createNamespace ( namespace : string , options ?: AdminBlockingOptions ) : Promise < void > {
80165 await this . _httpClient . request ( {
81166 method : HTTP_METHODS . Post ,
@@ -84,6 +169,37 @@ export class AstraDbAdmin extends DbAdmin {
84169 await this . _httpClient . awaitStatus ( this . _db , 'ACTIVE' , [ 'MAINTENANCE' ] , options , 1000 ) ;
85170 }
86171
172+ /**
173+ * Drops a namespace (aka keyspace) from this database.
174+ *
175+ * **NB. this is a "long-running" operation. See {@link AdminBlockingOptions} about such blocking operations.** The
176+ * default polling interval is 2 seconds. Expect it to take roughly 8-10 seconds to complete.
177+ *
178+ * @example
179+ * ```typescript
180+ * await dbAdmin.dropNamespace('my_other_keyspace1');
181+ *
182+ * // ['default_keyspace', 'my_other_keyspace2']
183+ * console.log(await dbAdmin.listNamespaces());
184+ *
185+ * await dbAdmin.dropNamespace('my_other_keyspace2', {
186+ * blocking: false,
187+ * });
188+ *
189+ * // Will still include 'my_other_keyspace2' until the operation completes
190+ * // ['default_keyspace', 'my_other_keyspace2']
191+ * console.log(await dbAdmin.listNamespaces());
192+ * ```
193+ *
194+ * @remarks
195+ * Note that if you choose not to block, the namespace object will still be able to be used until the operation
196+ * completes, which is up to the caller to determine.
197+ *
198+ * @param namespace - The name of the namespace to drop.
199+ * @param options - The options for the blocking behavior of the operation.
200+ *
201+ * @returns A promise that resolves when the operation completes.
202+ */
87203 public override async dropNamespace ( namespace : string , options ?: AdminBlockingOptions ) : Promise < void > {
88204 await this . _httpClient . request ( {
89205 method : HTTP_METHODS . Delete ,
@@ -92,6 +208,27 @@ export class AstraDbAdmin extends DbAdmin {
92208 await this . _httpClient . awaitStatus ( this . _db , 'ACTIVE' , [ 'MAINTENANCE' ] , options , 1000 ) ;
93209 }
94210
211+ /**
212+ * Drops the database.
213+ *
214+ * **NB. this is a long-running operation. See {@link AdminBlockingOptions} about such blocking operations.** The
215+ * default polling interval is 10 seconds. Expect it to take roughly 6-7 min to complete.
216+ *
217+ * The database info will still be accessible by ID, or by using the {@link listDatabases} method with the filter
218+ * set to `'ALL'` or `'TERMINATED'`. However, all of its data will very much be lost.
219+ *
220+ * @example
221+ * ```typescript
222+ * const db = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
223+ * await db.admin().drop();
224+ * ```
225+ *
226+ * @param options - The options for the blocking behavior of the operation.
227+ *
228+ * @returns A promise that resolves when the operation completes.
229+ *
230+ * @remarks Use with caution. Use a surge protector. Don't say I didn't warn you.
231+ */
95232 public async drop ( options ?: AdminBlockingOptions ) : Promise < void > {
96233 await this . _httpClient . request ( {
97234 method : HTTP_METHODS . Post ,
0 commit comments