EdgeBase Elixir Admin SDK

Trusted server-side Elixir SDK for EdgeBase.

Use edgebase_admin from Phoenix apps, Plug services, background jobs, and other trusted Elixir runtimes that hold a Service Key. It exposes admin auth, database access, raw SQL, storage, push, analytics, functions, and native edge resources.

This package uses a functional Elixir API. Most entry points return structs, and most service calls expose both non-bang and bang forms.

EdgeBase is the open-source edge-native BaaS that runs on Edge, Docker, and Node.js.

This package is one part of the wider EdgeBase platform. For the full platform, CLI, Admin Dashboard, server runtime, docs, and all public SDKs, see the main repository: edge-base/edgebase.

Documentation Map

Use this README for a fast overview, then jump into the docs when you need depth:

• SDK Overview Install commands and the public SDK matrix
• Admin SDK Trusted-server boundaries and admin-only capabilities
• Admin SDK Reference Cross-language examples for auth, database, storage, functions, push, and analytics
• Admin User Management Create, update, delete, and manage users with a Service Key
• Database Admin SDK Table queries, filters, pagination, batch writes, and raw SQL
• Storage Uploads, downloads, metadata, and signed URLs
• Analytics Admin SDK Request metrics, event tracking, and event queries
• Push Admin SDK Push send, topic broadcast, token inspection, and logs
• Native Resources KV, D1, Vectorize, and other trusted edge-native resources

For AI Coding Assistants

This package includes an llms.txt file for AI-assisted development.

Use it when you want an agent or code assistant to:

• keep Service Keys on trusted servers
• use the actual Elixir function names
• distinguish between non-bang functions that return {:ok, ...} and bang functions that raise on error
• avoid copying promise-based examples into Elixir

You can find it:

• in this repository: llms.txt
• in your environment after install, inside the EdgeBaseAdmin package directory as llms.txt

Installation

{:edgebase_admin, "~> 0.2.6"}

If you consume the monorepo directly, use the path dependency already configured in this repository.

Quick Start

admin = EdgeBaseAdmin.new(
  "https://your-project.edgebase.fun",
  service_key: System.fetch_env!("EDGEBASE_SERVICE_KEY")
)

auth = EdgeBaseAdmin.admin_auth(admin)
{:ok, user} = EdgeBaseAdmin.AdminAuth.get_user(auth, "user-123")

{:ok, rows} = EdgeBaseAdmin.sql(
  admin,
  "SELECT id, title FROM posts WHERE status = ?",
  namespace: "shared",
  params: ["published"]
)

push = EdgeBaseAdmin.push(admin)
{:ok, _} = EdgeBaseAdmin.Push.send(push, "user-123", %{
  "title" => "Deployment finished",
  "body" => "Your content is live."
})

Core API

Once you create an admin client, these are the main surfaces you will use:

• EdgeBaseAdmin.new/2 Main admin entry point
• EdgeBaseAdmin.db/3 Server-side database access
• EdgeBaseAdmin.storage/1 Storage client
• EdgeBaseAdmin.admin_auth/1 Admin user management
• EdgeBaseAdmin.auth/1 Alias for admin_auth/1
• EdgeBaseAdmin.functions/1 Call app functions from trusted code
• EdgeBaseAdmin.analytics/1 Query analytics and track server-side events
• EdgeBaseAdmin.kv/2, EdgeBaseAdmin.d1/2, EdgeBaseAdmin.vector/2 Native edge resources
• EdgeBaseAdmin.vectorize/2 Alias for vector/2
• EdgeBaseAdmin.push/1 Push notifications
• EdgeBaseAdmin.sql/3, EdgeBaseAdmin.sql!/3 Raw SQL execution
• EdgeBaseAdmin.broadcast/4, EdgeBaseAdmin.broadcast!/4 Server-side broadcast
• EdgeBaseAdmin.destroy/1 No-op cleanup hook

Database Access

db = EdgeBaseAdmin.db(admin, "app")
posts = EdgeBaseCore.DbRef.table(db, "posts")

For instance databases, pass the instance id as the third argument:

EdgeBaseAdmin.db(admin, "workspace", "ws-123")
EdgeBaseAdmin.db(admin, "user", "user-123")

Admin Users

auth = EdgeBaseAdmin.admin_auth(admin)

{:ok, created} =
  EdgeBaseAdmin.AdminAuth.create_user(auth, %{
    "email" => "admin@example.com",
    "password" => "secure-pass-123",
    "displayName" => "June"
  })

{:ok, _} = EdgeBaseAdmin.AdminAuth.set_custom_claims(auth, created["id"], %{
  "role" => "moderator"
})

{:ok, users} = EdgeBaseAdmin.AdminAuth.list_users(auth, limit: 20)

Raw SQL

rows =
  EdgeBaseAdmin.sql!(admin, "SELECT 1 AS ok", namespace: "shared")

workspace_rows =
  EdgeBaseAdmin.sql!(admin, "SELECT * FROM documents WHERE status = ?",
    namespace: "workspace",
    instance_id: "ws-123",
    params: ["published"]
  )

Push And Analytics

push = EdgeBaseAdmin.push(admin)

{:ok, _} =
  EdgeBaseAdmin.Push.send(push, "user-123", %{
    "title" => "Hello",
    "body" => "From the admin SDK"
  })

analytics = EdgeBaseAdmin.analytics(admin)
{:ok, overview} = EdgeBaseAdmin.Analytics.overview(analytics, %{ "range" => "7d" })

Choose The Right Package

License

MIT