appwrite-utils-cli 1.4.1 → 1.5.1

package/dist/utils/setupFiles.js

@@ -1,6 +1,8 @@
 import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import path from "node:path";
 import { findAppwriteConfig } from "./loadConfigs.js";
+import { loadYamlConfig } from "../config/yamlConfig.js";
+import { fetchServerVersion, isVersionAtLeast } from "./versionDetection.js";
 import { findYamlConfig } from "../config/yamlConfig.js";
 import { ID } from "node-appwrite";
 import { ulid } from "ulidx";
@@ -240,7 +242,23 @@ export const setupDirsFiles = async (example = false, currentDir, useYaml = true
     const appwriteSchemaFolder = path.join(appwriteFolder, "schemas");
     const appwriteYamlSchemaFolder = path.join(appwriteFolder, ".yaml_schemas");
     const appwriteDataFolder = path.join(appwriteFolder, "importData");
-    const collectionsFolder = path.join(appwriteFolder, "collections");
+    // Decide between collections or tables folder
+    let useTables = false;
+    try {
+        // Try reading YAML config if present to detect version
+        const yamlPath = findYamlConfig(basePath);
+        if (yamlPath) {
+            const cfg = await loadYamlConfig(yamlPath);
+            if (cfg) {
+                const ver = await fetchServerVersion(cfg.appwriteEndpoint);
+                if (isVersionAtLeast(ver || undefined, '1.8.0'))
+                    useTables = true;
+            }
+        }
+    }
+    catch { }
+    const targetFolderName = useTables ? "tables" : "collections";
+    const collectionsFolder = path.join(appwriteFolder, targetFolderName);
     // Create directory structure
     if (!existsSync(appwriteFolder)) {
         mkdirSync(appwriteFolder, { recursive: true });

package/dist/utils/versionDetection.d.ts

@@ -54,3 +54,9 @@ export declare function detectSdkSupport(): Promise<{
  * Clear version detection cache (useful for testing)
  */
 export declare function clearVersionDetectionCache(): void;
+/**
+ * Fetch server version from /health/version (no auth required)
+ */
+export declare function fetchServerVersion(endpoint: string): Promise<string | null>;
+/** Compare semantic versions (basic) */
+export declare function isVersionAtLeast(current: string | undefined, target: string): boolean;

package/dist/utils/versionDetection.js

@@ -215,3 +215,33 @@ export async function detectSdkSupport() {
 export function clearVersionDetectionCache() {
     detectionCache.clear();
 }
+/**
+ * Fetch server version from /health/version (no auth required)
+ */
+export async function fetchServerVersion(endpoint) {
+    try {
+        const clean = endpoint.replace(/\/$/, '');
+        const res = await fetch(`${clean}/health/version`, { method: 'GET', signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            return null;
+        const data = await res.json().catch(() => null);
+        const version = (data && (data.version || data.build || data.release)) ?? null;
+        return typeof version === 'string' ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compare semantic versions (basic) */
+export function isVersionAtLeast(current, target) {
+    if (!current)
+        return false;
+    const toNums = (v) => v.split('.').map(n => parseInt(n, 10));
+    const [a1 = 0, a2 = 0, a3 = 0] = toNums(current);
+    const [b1, b2, b3] = toNums(target);
+    if (a1 !== b1)
+        return a1 > b1;
+    if (a2 !== b2)
+        return a2 > b2;
+    return a3 >= b3;
+}

package/dist/utilsController.js

@@ -7,12 +7,14 @@ import { ImportController } from "./migrations/importController.js";
 import { ImportDataActions } from "./migrations/importDataActions.js";
 import { setupMigrationDatabase, ensureDatabasesExist, wipeOtherDatabases, ensureCollectionsExist, } from "./databases/setup.js";
 import { createOrUpdateCollections, wipeDatabase, generateSchemas, fetchAllCollections, wipeCollection, } from "./collections/methods.js";
+import { wipeAllTables, wipeTableRows } from "./collections/methods.js";
 import { backupDatabase, ensureDatabaseConfigBucketsExist, initOrGetBackupStorage, wipeDocumentStorage, } from "./storage/methods.js";
 import path from "path";
 import { converterFunctions, validationRules, } from "appwrite-utils";
 import { afterImportActions } from "./migrations/afterImportActions.js";
 import { transferDatabaseLocalToLocal, transferDatabaseLocalToRemote, transferStorageLocalToLocal, transferStorageLocalToRemote, transferUsersLocalToRemote, } from "./migrations/transfer.js";
 import { getClient } from "./utils/getClientFromConfig.js";
+import { getAdapterFromConfig } from "./utils/getClientFromConfig.js";
 import { fetchAllDatabases } from "./databases/methods.js";
 import { listFunctions, updateFunctionSpecifications, } from "./functions/methods.js";
 import chalk from "chalk";
@@ -291,9 +293,20 @@ export class UtilsController {
     }
     async wipeDatabase(database, wipeBucket = false) {
         await this.init();
-        if (!this.database)
+        if (!this.database || !this.config)
             throw new Error("Database not initialized");
-        await wipeDatabase(this.database, database.$id);
+        try {
+            const { adapter, apiMode } = await getAdapterFromConfig(this.config);
+            if (apiMode === 'tablesdb') {
+                await wipeAllTables(adapter, database.$id);
+            }
+            else {
+                await wipeDatabase(this.database, database.$id);
+            }
+        }
+        catch {
+            await wipeDatabase(this.database, database.$id);
+        }
         if (wipeBucket) {
             await this.wipeBucketFromDatabase(database);
         }
@@ -323,9 +336,20 @@ export class UtilsController {
     }
     async wipeCollection(database, collection) {
         await this.init();
-        if (!this.database)
+        if (!this.database || !this.config)
             throw new Error("Database not initialized");
-        await wipeCollection(this.database, database.$id, collection.$id);
+        try {
+            const { adapter, apiMode } = await getAdapterFromConfig(this.config);
+            if (apiMode === 'tablesdb') {
+                await wipeTableRows(adapter, database.$id, collection.$id);
+            }
+            else {
+                await wipeCollection(this.database, database.$id, collection.$id);
+            }
+        }
+        catch {
+            await wipeCollection(this.database, database.$id, collection.$id);
+        }
     }
     async wipeDocumentStorage(bucketId) {
         await this.init();
@@ -418,9 +442,12 @@ export class UtilsController {
             const allDatabases = await fetchAllDatabases(this.database);
             databases = allDatabases;
         }
+        // Ensure DBs exist (this may internally ensure migrations exists)
         await this.ensureDatabasesExist(databases);
         await this.ensureDatabaseConfigBucketsExist(databases);
-        await this.createOrUpdateCollectionsForDatabases(databases, collections);
+        // Do not push collections to the migrations database (prevents duplicate runs)
+        const dbsForCollections = databases.filter((db) => (this.config?.useMigrations ?? true) ? db.name.toLowerCase() !== "migrations" : true);
+        await this.createOrUpdateCollectionsForDatabases(dbsForCollections, collections);
     }
     getAppwriteFolderPath() {
         return this.appwriteFolderPath;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "main": "src/main.ts",
   "type": "module",
   "repository": {

package/src/adapters/TablesDBAdapter.ts

@@ -246,12 +246,13 @@ export class TablesDBAdapter extends BaseAdapter {
   }
   
   // Attribute Operations
-  async createAttribute(params: CreateAttributeParams): Promise<ApiResponse> {
-    try {
-      // TablesDB may have different method names for attribute operations
-      const result = await this.tablesDB.createAttribute(params);
-      return { data: result };
-    } catch (error) {
+  async createAttribute(params: CreateAttributeParams): Promise<ApiResponse> {
+    try {
+      // Prefer createColumn if available, fallback to createAttribute
+      const fn = this.tablesDB.createColumn || this.tablesDB.createAttribute;
+      const result = await fn.call(this.tablesDB, params);
+      return { data: result };
+    } catch (error) {
       throw new AdapterError(
         `Failed to create attribute: ${error instanceof Error ? error.message : 'Unknown error'}`,
         'CREATE_ATTRIBUTE_FAILED',
@@ -260,11 +261,12 @@ export class TablesDBAdapter extends BaseAdapter {
     }
   }
   
-  async updateAttribute(params: UpdateAttributeParams): Promise<ApiResponse> {
-    try {
-      const result = await this.tablesDB.updateAttribute(params);
-      return { data: result };
-    } catch (error) {
+  async updateAttribute(params: UpdateAttributeParams): Promise<ApiResponse> {
+    try {
+      const fn = this.tablesDB.updateColumn || this.tablesDB.updateAttribute;
+      const result = await fn.call(this.tablesDB, params);
+      return { data: result };
+    } catch (error) {
       throw new AdapterError(
         `Failed to update attribute: ${error instanceof Error ? error.message : 'Unknown error'}`,
         'UPDATE_ATTRIBUTE_FAILED',
@@ -273,11 +275,12 @@ export class TablesDBAdapter extends BaseAdapter {
     }
   }
   
-  async deleteAttribute(params: DeleteAttributeParams): Promise<ApiResponse> {
-    try {
-      const result = await this.tablesDB.deleteAttribute(params);
-      return { data: result };
-    } catch (error) {
+  async deleteAttribute(params: DeleteAttributeParams): Promise<ApiResponse> {
+    try {
+      const fn = this.tablesDB.deleteColumn || this.tablesDB.deleteAttribute;
+      const result = await fn.call(this.tablesDB, params);
+      return { data: result };
+    } catch (error) {
       throw new AdapterError(
         `Failed to delete attribute: ${error instanceof Error ? error.message : 'Unknown error'}`,
         'DELETE_ATTRIBUTE_FAILED',
@@ -426,4 +429,4 @@ export class TablesDBAdapter extends BaseAdapter {
       );
     }
   }
-}
+}

package/src/collections/attributes.ts

@@ -224,33 +224,33 @@ const attributesSame = (
   databaseAttribute: Attribute,
   configAttribute: Attribute
 ): boolean => {
-  const attributesToCheck = [
-    "key",
-    "type",
-    "array",
-    "encrypted",
-    "required",
-    "size",
-    "min",
-    "max",
-    "xdefault",
-    "elements",
-    "relationType",
-    "twoWay",
-    "twoWayKey",
-    "onDelete",
-    "relatedCollection",
-  ];
-
-  return attributesToCheck.every((attr) => {
-    // Check if both objects have the attribute
-    const dbHasAttr = attr in databaseAttribute;
-    const configHasAttr = attr in configAttribute;
+  const attributesToCheck = [
+    "key",
+    "type",
+    "array",
+    "encrypted",
+    "required",
+    "size",
+    "min",
+    "max",
+    "xdefault",
+    "elements",
+    "relationType",
+    "twoWay",
+    "twoWayKey",
+    "onDelete",
+    "relatedCollection",
+  ];
+
+  return attributesToCheck.every((attr) => {
+    // Check if both objects have the attribute
+    const dbHasAttr = attr in databaseAttribute;
+    const configHasAttr = attr in configAttribute;
 
     // If both have the attribute, compare values
-    if (dbHasAttr && configHasAttr) {
-      const dbValue = databaseAttribute[attr as keyof typeof databaseAttribute];
-      const configValue = configAttribute[attr as keyof typeof configAttribute];
+    if (dbHasAttr && configHasAttr) {
+      const dbValue = databaseAttribute[attr as keyof typeof databaseAttribute];
+      const configValue = configAttribute[attr as keyof typeof configAttribute];
 
       // Consider undefined and null as equivalent
       if (
@@ -260,8 +260,19 @@ const attributesSame = (
         return true;
       }
 
-      return dbValue === configValue;
-    }
+      // Normalize booleans: treat undefined and false as equivalent
+      if (typeof dbValue === "boolean" || typeof configValue === "boolean") {
+        return Boolean(dbValue) === Boolean(configValue);
+      }
+      // For numeric comparisons, compare numbers if both are numeric-like
+      if (
+        (typeof dbValue === "number" || (typeof dbValue === "string" && dbValue !== "" && !isNaN(Number(dbValue)))) &&
+        (typeof configValue === "number" || (typeof configValue === "string" && configValue !== "" && !isNaN(Number(configValue))))
+      ) {
+        return Number(dbValue) === Number(configValue);
+      }
+      return dbValue === configValue;
+    }
 
     // If neither has the attribute, consider it the same
     if (!dbHasAttr && !configHasAttr) {
@@ -269,15 +280,23 @@ const attributesSame = (
     }
 
     // If one has the attribute and the other doesn't, check if it's undefined or null
-    if (dbHasAttr && !configHasAttr) {
-      const dbValue = databaseAttribute[attr as keyof typeof databaseAttribute];
-      return dbValue === undefined || dbValue === null;
-    }
-
-    if (!dbHasAttr && configHasAttr) {
-      const configValue = configAttribute[attr as keyof typeof configAttribute];
-      return configValue === undefined || configValue === null;
-    }
+    if (dbHasAttr && !configHasAttr) {
+      const dbValue = databaseAttribute[attr as keyof typeof databaseAttribute];
+      // Consider default-false booleans as equal to missing in config
+      if (typeof dbValue === "boolean") {
+        return dbValue === false; // missing in config equals false in db
+      }
+      return dbValue === undefined || dbValue === null;
+    }
+
+    if (!dbHasAttr && configHasAttr) {
+      const configValue = configAttribute[attr as keyof typeof configAttribute];
+      // Consider default-false booleans as equal to missing in db
+      if (typeof configValue === "boolean") {
+        return configValue === false; // missing in db equals false in config
+      }
+      return configValue === undefined || configValue === null;
+    }
 
     // If we reach here, the attributes are different
     return false;
@@ -287,14 +306,14 @@ const attributesSame = (
 /**
  * Enhanced attribute creation with proper status monitoring and retry logic
  */
-export const createOrUpdateAttributeWithStatusCheck = async (
-  db: Databases,
-  dbId: string,
-  collection: Models.Collection,
-  attribute: Attribute,
-  retryCount: number = 0,
-  maxRetries: number = 5
-): Promise<boolean> => {
+export const createOrUpdateAttributeWithStatusCheck = async (
+  db: Databases,
+  dbId: string,
+  collection: Models.Collection,
+  attribute: Attribute,
+  retryCount: number = 0,
+  maxRetries: number = 5
+): Promise<boolean> => {
   console.log(
     chalk.blue(
       `Creating/updating attribute '${attribute.key}' (attempt ${
@@ -303,20 +322,31 @@ export const createOrUpdateAttributeWithStatusCheck = async (
     )
   );
 
-  try {
-    // First, try to create/update the attribute using existing logic
-    await createOrUpdateAttribute(db, dbId, collection, attribute);
-
-    // Now wait for the attribute to become available
-    const success = await waitForAttributeAvailable(
-      db,
-      dbId,
-      collection.$id,
-      attribute.key,
-      60000, // 1 minute timeout
-      retryCount,
-      maxRetries
-    );
+  try {
+    // First, try to create/update the attribute using existing logic
+    const result = await createOrUpdateAttribute(db, dbId, collection, attribute);
+
+    // If the attribute was queued (relationship dependency unresolved),
+    // skip status polling and retry logic — the queue will handle it later.
+    if (result === "queued") {
+      console.log(
+        chalk.yellow(
+          `⏭️  Deferred relationship attribute '${attribute.key}' — queued for later once dependencies are available`
+        )
+      );
+      return true;
+    }
+
+    // Now wait for the attribute to become available
+    const success = await waitForAttributeAvailable(
+      db,
+      dbId,
+      collection.$id,
+      attribute.key,
+      60000, // 1 minute timeout
+      retryCount,
+      maxRetries
+    );
 
     if (success) {
       return true;
@@ -440,12 +470,12 @@ export const createOrUpdateAttributeWithStatusCheck = async (
   }
 };
 
-export const createOrUpdateAttribute = async (
-  db: Databases,
-  dbId: string,
-  collection: Models.Collection,
-  attribute: Attribute
-): Promise<void> => {
+export const createOrUpdateAttribute = async (
+  db: Databases,
+  dbId: string,
+  collection: Models.Collection,
+  attribute: Attribute
+): Promise<"queued" | "processed"> => {
   let action = "create";
   let foundAttribute: Attribute | undefined;
   const updateEnabled = true;
@@ -460,13 +490,13 @@ export const createOrUpdateAttribute = async (
     foundAttribute = undefined;
   }
 
-  if (
-    foundAttribute &&
-    attributesSame(foundAttribute, attribute) &&
-    updateEnabled
-  ) {
-    // No need to do anything, they are the same
-    return;
+  if (
+    foundAttribute &&
+    attributesSame(foundAttribute, attribute) &&
+    updateEnabled
+  ) {
+    // No need to do anything, they are the same
+    return "processed";
   } else if (
     foundAttribute &&
     !attributesSame(foundAttribute, attribute) &&
@@ -484,71 +514,82 @@ export const createOrUpdateAttribute = async (
     !updateEnabled &&
     foundAttribute &&
     !attributesSame(foundAttribute, attribute)
-  ) {
-    await db.deleteAttribute(dbId, collection.$id, attribute.key);
-    console.log(
-      `Deleted attribute: ${attribute.key} to recreate it because they diff (update disabled temporarily)`
-    );
-    return;
-  }
+  ) {
+    await db.deleteAttribute(dbId, collection.$id, attribute.key);
+    console.log(
+      `Deleted attribute: ${attribute.key} to recreate it because they diff (update disabled temporarily)`
+    );
+    return "processed";
+  }
 
   // console.log(`${action}-ing attribute: ${finalAttribute.key}`);
 
   // Relationship attribute logic with adjustments
   let collectionFoundViaRelatedCollection: Models.Collection | undefined;
   let relatedCollectionId: string | undefined;
-  if (
-    finalAttribute.type === "relationship" &&
-    finalAttribute.relatedCollection
-  ) {
-    if (nameToIdMapping.has(finalAttribute.relatedCollection)) {
-      relatedCollectionId = nameToIdMapping.get(
-        finalAttribute.relatedCollection
-      );
-      try {
-        collectionFoundViaRelatedCollection = await db.getCollection(
-          dbId,
-          relatedCollectionId!
-        );
-      } catch (e) {
-        // console.log(
-        //   `Collection not found: ${finalAttribute.relatedCollection} when nameToIdMapping was set`
-        // );
-        collectionFoundViaRelatedCollection = undefined;
-      }
-    } else {
-      const collectionsPulled = await db.listCollections(dbId, [
-        Query.equal("name", finalAttribute.relatedCollection),
-      ]);
-      if (collectionsPulled.total > 0) {
-        collectionFoundViaRelatedCollection = collectionsPulled.collections[0];
-        relatedCollectionId = collectionFoundViaRelatedCollection.$id;
-        nameToIdMapping.set(
-          finalAttribute.relatedCollection,
-          relatedCollectionId
-        );
-      }
-    }
-    // ONLY queue relationship attributes that have actual unresolved dependencies
-    if (!(relatedCollectionId && collectionFoundViaRelatedCollection)) {
-      console.log(
-        chalk.yellow(
-          `⏳ Queueing relationship attribute '${finalAttribute.key}' - related collection '${finalAttribute.relatedCollection}' not found yet`
-        )
-      );
-      enqueueOperation({
-        type: "attribute",
-        collectionId: collection.$id,
-        collection: collection,
-        attribute,
-        dependencies: [finalAttribute.relatedCollection],
-      });
-      return;
-    }
-  }
-  finalAttribute = parseAttribute(finalAttribute);
-  // console.log(`Final Attribute: ${JSON.stringify(finalAttribute)}`);
-  switch (finalAttribute.type) {
+  if (
+    finalAttribute.type === "relationship" &&
+    finalAttribute.relatedCollection
+  ) {
+    // First try treating relatedCollection as an ID directly
+    try {
+      const byIdCollection = await db.getCollection(dbId, finalAttribute.relatedCollection);
+      collectionFoundViaRelatedCollection = byIdCollection;
+      relatedCollectionId = byIdCollection.$id;
+      // Cache by name for subsequent lookups
+      nameToIdMapping.set(byIdCollection.name, byIdCollection.$id);
+    } catch (_) {
+      // Not an ID or not found — fall back to name-based resolution below
+    }
+
+    if (!collectionFoundViaRelatedCollection && nameToIdMapping.has(finalAttribute.relatedCollection)) {
+      relatedCollectionId = nameToIdMapping.get(
+        finalAttribute.relatedCollection
+      );
+      try {
+        collectionFoundViaRelatedCollection = await db.getCollection(
+          dbId,
+          relatedCollectionId!
+        );
+      } catch (e) {
+        // console.log(
+        //   `Collection not found: ${finalAttribute.relatedCollection} when nameToIdMapping was set`
+        // );
+        collectionFoundViaRelatedCollection = undefined;
+      }
+    } else if (!collectionFoundViaRelatedCollection) {
+      const collectionsPulled = await db.listCollections(dbId, [
+        Query.equal("name", finalAttribute.relatedCollection),
+      ]);
+      if (collectionsPulled.total > 0) {
+        collectionFoundViaRelatedCollection = collectionsPulled.collections[0];
+        relatedCollectionId = collectionFoundViaRelatedCollection.$id;
+        nameToIdMapping.set(
+          finalAttribute.relatedCollection,
+          relatedCollectionId
+        );
+      }
+    }
+    // ONLY queue relationship attributes that have actual unresolved dependencies
+    if (!(relatedCollectionId && collectionFoundViaRelatedCollection)) {
+      console.log(
+        chalk.yellow(
+          `⏳ Queueing relationship attribute '${finalAttribute.key}' - related collection '${finalAttribute.relatedCollection}' not found yet`
+        )
+      );
+      enqueueOperation({
+        type: "attribute",
+        collectionId: collection.$id,
+        collection: collection,
+        attribute,
+        dependencies: [finalAttribute.relatedCollection],
+      });
+      return "queued";
+    }
+  }
+  finalAttribute = parseAttribute(finalAttribute);
+  // console.log(`Final Attribute: ${JSON.stringify(finalAttribute)}`);
+  switch (finalAttribute.type) {
     case "string":
       if (action === "create") {
         await tryAwaitWithRetry(
@@ -624,27 +665,27 @@ export const createOrUpdateAttribute = async (
               finalAttribute.array || false
             )
         );
-      } else {
-        if (
-          finalAttribute.min &&
-          BigInt(finalAttribute.min) === BigInt(-9223372036854776000)
-        ) {
-          finalAttribute.min = undefined;
-        }
-        if (
-          finalAttribute.max &&
-          BigInt(finalAttribute.max) === BigInt(9223372036854776000)
-        ) {
-          finalAttribute.max = undefined;
-        }
-        const minValue =
-          finalAttribute.min !== undefined && finalAttribute.min !== null
-            ? parseInt(finalAttribute.min)
-            : 9007199254740991;
-        const maxValue =
-          finalAttribute.max !== undefined && finalAttribute.max !== null
-            ? parseInt(finalAttribute.max)
-            : 9007199254740991;
+      } else {
+        if (
+          finalAttribute.min &&
+          BigInt(finalAttribute.min) === BigInt(-9223372036854776000)
+        ) {
+          finalAttribute.min = undefined;
+        }
+        if (
+          finalAttribute.max &&
+          BigInt(finalAttribute.max) === BigInt(9223372036854776000)
+        ) {
+          finalAttribute.max = undefined;
+        }
+        const minValue =
+          finalAttribute.min !== undefined && finalAttribute.min !== null
+            ? parseInt(finalAttribute.min)
+            : -9007199254740991;
+        const maxValue =
+          finalAttribute.max !== undefined && finalAttribute.max !== null
+            ? parseInt(finalAttribute.max)
+            : 9007199254740991;
         console.log(
           `DEBUG: Updating integer attribute '${
             finalAttribute.key
@@ -910,11 +951,12 @@ export const createOrUpdateAttribute = async (
         );
       }
       break;
-    default:
-      console.error("Invalid attribute type");
-      break;
-  }
-};
+    default:
+      console.error("Invalid attribute type");
+      break;
+  }
+  return "processed";
+};
 
 /**
  * Enhanced collection attribute creation with proper status monitoring