appres

AppRes - Appwrite Resource Creator

A Go package for creating and managing Appwrite resources programmatically. This package simplifies the process of creating databases, collections, and attributes in your Appwrite backend.

Features

• Create databases with duplicate checking
• Create collections with duplicate checking
• Create attributes with full configuration support for multiple types:
  • String attributes with size, encryption, and array support
  • Email attributes with validation and array support
  • Integer attributes with min/max constraints and array support
  • DateTime attributes with default values and array support
  • Boolean attributes with default values and array support
• Environment-based configuration
• Comprehensive error handling and logging

Installation

Install the package using go get:

go get github.com/Haepapa/appres

Setup

1. Environment Configuration

Create a .env.local file in your project root with your Appwrite configuration:

NEXT_PUBLIC_APPWRITE_ENDPOINT=https://your-appwrite-endpoint.com/v1
NEXT_PUBLIC_APPWRITE_PROJECT=your-project-id
APPWRITE_API_KEY_RESDEF=your-api-key #api key with all Database scopes

2. Import the Package

import (
    "crypto/tls"
    "log"
    "net/http"
    
    app "github.com/Haepapa/appres"
)

Usage

Basic Example

Here's a complete example showing how to create a database, collection, and attributes:

package main

import (
    "crypto/tls"
    "log"
    "net/http"
    
    app "github.com/Haepapa/appres"
)

func main() {
    // Suppress insecure warning (if using self-signed certificates)
    http.DefaultTransport.(*http.Transport).TLSClientConfig = &tls.Config{InsecureSkipVerify: true}

    // Initialize Appwrite client
    app.Utils()

    // Create a database
    db, err := app.CreateDatabase("synergysquares")
    if err != nil {
        log.Println("Error creating database:", err)
        return
    }

    // Create collection(s)
    colContactUs, err := app.CreateCollection(db.Id, "contact_us")
    if err != nil {
        log.Println("Error creating collection:", err)
        return
    }

    // Create attributes in collection(s)
    attVals := []app.AttributeType{
        {
            Type:        "string",
            Name:        "name",
            Size:        100,
            Required:    false,
            Default:     "",
            Array:       false,
            Encrypt:     false,
        },
        {
            Type:        "email",
            Name:        "email",
            Size:        200,
            Required:    false,
            Default:     "email@email.com",
            Array:       false,
            Encrypt:     false,
        },
        {
            Type:        "string",
            Name:        "subject",
            Size:        200,
            Required:    false,
            Default:     "",
            Array:       false,
            Encrypt:     false,
        },
        {
            Type:        "string",
            Name:        "message",
            Size:        5000,
            Required:    false,
            Default:     "",
            Array:       false,
            Encrypt:     false,
        },
        {
            Type:        "integer",
            Name:        "priority",
            Required:    false,
            Default:     "1",
            Min:         1,
            Max:         5,
            Array:       false,
        },
        {
            Type:        "datetime",
            Name:        "created_at",
            Required:    true,
            Array:       false,
        },
        {
            Type:        "boolean",
            Name:        "is_resolved",
            Required:    false,
            Default:     "false",
            Array:       false,
        },
    }

    for _, att := range attVals {
        err = app.CreateAttribute(db.Id, colContactUs.Id, att)
        if err != nil {
            log.Println("Error creating attribute:", err)
            return
        }
    }

    log.Println("Successfully created database, collection, and attributes!")
}

API Reference

Functions

Utils()

Initializes the Appwrite client with environment variables. Must be called before using other functions.

app.Utils()

CreateDatabase(name string) (*models.Database, error)

Creates a new database or returns existing one if it already exists.

db, err := app.CreateDatabase("my-database")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Database ID:", db.Id)

CreateCollection(dbId string, name string) (*models.Collection, error)

Creates a new collection in the specified database or returns existing one if it already exists.

col, err := app.CreateCollection(db.Id, "my-collection")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Collection ID:", col.Id)

CreateAttribute(dbID string, colID string, att AttributeType) error

Creates a new attribute in the specified collection or skips if it already exists.

attr := app.AttributeType{
    Type:     "string",
    Name:     "title",
    Size:     255,
    Required: true,
    Default:  "",
    Array:    false,
    Encrypt:  false,
}

err := app.CreateAttribute(db.Id, col.Id, attr)
if err != nil {
    log.Fatal(err)
}

Attribute Examples

Here are examples of creating different attribute types:

// String attribute with encryption
stringAttr := app.AttributeType{
    Type:     "string",
    Name:     "username",
    Size:     50,
    Required: true,
    Default:  "",
    Array:    false,
    Encrypt:  true,
}

// Email attribute
emailAttr := app.AttributeType{
    Type:     "email",
    Name:     "user_email",
    Size:     255,
    Required: true,
    Default:  "",
    Array:    false,
}

// Integer attribute with min/max constraints
integerAttr := app.AttributeType{
    Type:     "integer",
    Name:     "age",
    Required: false,
    Default:  "18",
    Min:      0,
    Max:      120,
    Array:    false,
}

// DateTime attribute
datetimeAttr := app.AttributeType{
    Type:     "datetime",
    Name:     "created_at",
    Required: true,
    Array:    false,
}

// Boolean attribute
booleanAttr := app.AttributeType{
    Type:     "boolean",
    Name:     "is_active",
    Required: false,
    Default:  "true",
    Array:    false,
}

// Array attribute example
arrayAttr := app.AttributeType{
    Type:     "string",
    Name:     "tags",
    Size:     50,
    Required: false,
    Array:    true, // This creates an array of strings
}

Types

AttributeType

Defines the structure for creating attributes:

type AttributeType struct {
    Type     string // Supported: "string", "email", "integer", "datetime", "boolean"
    Name     string // Attribute key/name
    Size     int    // Maximum size (for string/email attributes)
    Required bool   // Whether the attribute is required
    Default  string // Default value
    Array    bool   // Whether the attribute is an array
    Encrypt  bool   // Whether to encrypt the attribute (string only)
    Min      int    // Minimum value (for integer attributes)
    Max      int    // Maximum value (for integer attributes)
}

Supported Attribute Types

• string: Text attributes with configurable size, encryption, and array support

  • Size: Maximum character length (required)
  • Encrypt: Enable encryption at rest (optional)
  • Default: Default string value (optional)

• email: Email validation attributes with array support

  • Size: Maximum character length (required)
  • Default: Default email value (optional)

• integer: Integer attributes with configurable min/max constraints and array support

  • Min: Minimum allowed value (optional, 0 = no constraint)
  • Max: Maximum allowed value (optional, 0 = no constraint)
  • Default: Default integer value as string (optional)

• datetime: Date and time attributes with default values and array support

  • Default: Default datetime value in ISO 8601 format (optional)

• boolean: Boolean (true/false) attributes with default values and array support

  • Default: Default boolean value as string "true" or "false" (optional)

Common Configuration Options:

• Required: Whether the attribute must have a value (all types)
• Array: Whether the attribute stores multiple values as an array (all types)

Environment Variables

Error Handling

All functions return appropriate errors that should be handled:

db, err := app.CreateDatabase("test-db")
if err != nil {
    log.Printf("Failed to create database: %v", err)
    return
}

The package also provides detailed logging for debugging purposes.

Requirements

• Go 1.22.5 or later
• Active Appwrite server instance
• Valid API key with database creation permissions

License

This project is licensed under the terms included in the LICENSE file.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.