Skip to content

Latest commit

 

History

History
573 lines (408 loc) · 14.5 KB

README.md

File metadata and controls

573 lines (408 loc) · 14.5 KB
Raw

Azion Edge SQL Client

Azion Edge SQL Client provides a simple interface to interact with the Azion Edge SQL API, allowing you to create, delete, and query databases. This client is configurable and supports both debug mode and environment variable-based configuration.

Table of Contents

Installation

Install the package using npm or yarn:

npm install azion

or

yarn add azion

Environment Variables

You can configure the client using the following environment variables:

  • AZION_TOKEN: Your Azion API token.
  • AZION_DEBUG: Enable debug mode (true/false).

Example .env file:

AZION_TOKEN=your-api-token
AZION_DEBUG=true

Debug Mode

Debug mode provides detailed logging of the API requests and responses. You can enable debug mode by setting the AZION_DEBUG environment variable to true or by passing true as the debug parameter in the methods.

Usage

Using Environment Variables

You can use the environment variables to configure the client without passing the token and debug parameters directly.

Direct Method Calls

You can use the provided wrapper methods to perform database operations directly.

Client Configuration

You can create a client instance with specific configurations.

API Examples

Create Database

JavaScript:

import { createDatabase } from 'azion/sql';

const { data, error } = await createDatabase('my-new-database', { debug: true });
if (data) {
  console.log(`Database created with ID: ${data.id}`);
} else {
  console.error('Failed to create database', error);
}

TypeScript:

import { createDatabase, AzionDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabase } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabase> = await createDatabase('my-new-database', { debug: true });
if (data) {
  const database: AzionDatabase = data;
  console.log(`Database created with ID: ${database.id}`);
} else {
  console.error('Failed to create database', error);
}

Delete Database

JavaScript:

import { deleteDatabase } from 'azion/sql';

const { data, error } = await deleteDatabase(123, { debug: true });
if (data) {
  console.log(`Database ${data.id} deleted successfully`);
} else {
  console.error('Failed to delete database', error);
}

TypeScript:

import { deleteDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabaseDeleteResponse } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabaseDeleteResponse> = await deleteDatabase(123, { debug: true });
if (data) {
  console.log(`Database ${data.id} deleted successfully`);
} else {
  console.error('Failed to delete database', error);
}

Get Database

JavaScript:

import { getDatabase } from 'azion/sql';

const { data, error } = await getDatabase('my-db', { debug: true });
if (data) {
  console.log(`Retrieved database: ${data.id}`);
} else {
  console.error('Database not found', error);
}

TypeScript:

import { getDatabase } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabase } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabase> = await getDatabase('my-db', { debug: true });
if (data) {
  const database: AzionDatabase = data;
  console.log(`Retrieved database: ${database.id}`);
} else {
  console.error('Database not found', error);
}

Get Databases

JavaScript:

import { getDatabases } from 'azion/sql';

const { data, error } = await getDatabases({ page: 1, page_size: 10 }, { debug: true });
if (data) {
  console.log(`Retrieved ${data.length} databases`);
} else {
  console.error('Failed to retrieve databases', error);
}

TypeScript:

import { getDatabases } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabaseCollections } from 'azion/sql';

const { data: allDatabases, error }: AzionDatabaseResponse<AzionDatabaseCollections> = await getDatabases(
  { page: 1, page_size: 10 },
  { debug: true },
);
if (allDatabases) {
  console.log(`Retrieved ${allDatabases.count} databases`);
} else {
  console.error('Failed to retrieve databases', error);
}

Use Query

JavaScript:

import { useQuery } from 'azion/sql';

const result = await useQuery('my-db', ['SELECT * FROM users'], { debug: true });
if (result) {
  console.log(`Query executed. Rows returned: ${result.rows.length}`);
} else {
  console.error('Query execution failed');
}

TypeScript:

import { useQuery, AzionDatabaseQueryResponse, AzionDatabaseResponse } from 'azion/sql';

const { data: result, error }: AzionDatabaseResponse<AzionDatabaseQueryResponse> = await useQuery(
  'my-db',
  ['SELECT * FROM users'],
  {
    debug: true,
  },
);
if (result) {
  console.log(`Query executed. Rows returned: ${result.rows.length}`);
} else {
  console.error('Query execution failed', error);
}

Use Execute

JavaScript:

import { useExecute } from 'azion/sql';

const result = await useExecute('my-db', ['INSERT INTO users (name) VALUES ("John")'], { debug: true });
if (result?.state === 'executed') {
  console.log('Executed with success');
} else {
  console.error('Execution failed');
}

TypeScript:

import { useExecute, AzionDatabaseQueryResponse } from 'azion/sql';

const result: AzionDatabaseQueryResponse | null = await useExecute(
  'my-db',
  ['INSERT INTO users (name) VALUES ("John")'],
  {
    debug: true,
  },
);
if (result?.state === 'executed') {
  console.log('Executed with success');
} else {
  console.error('Execution failed');
}

List Tables

JavaScript:

import { getTables } from 'azion/sql';

const { data, error } = await getTables('my-db', { debug: true });

if (data) {
  console.log(data);
} else {
  console.error('Query execution failed', error);
}

TypeScript:

import { getTables } from 'azion/sql';
import type { AzionDatabaseResponse, AzionDatabaseQueryResponse } from 'azion/sql';

const { data, error }: AzionDatabaseResponse<AzionDatabaseQueryResponse> = await getTables('my-db', { debug: true });

if (data) {
  console.log(data);
} else {
  console.error('Query execution failed', error);
}

API Reference

createDatabase

Creates a new database.

Parameters:

  • name: string - Name of the new database.
  • options?: AzionClientOptions - Optional parameters for the creation.

Returns:

  • Promise<AzionDatabaseResponse<AzionDatabase>> - The created database object or error.

Example:

const { data, error } = await sqlClient.createDatabase('my-new-db');
if (data) {
  console.log(`Database created with ID: ${data.id}`);
} else {
  console.error('Failed to create database', error);
}

deleteDatabase

Deletes a database by its ID.

Parameters:

  • id: number - ID of the database to delete.
  • options?: AzionClientOptions - Optional parameters for the deletion.

Returns:

  • Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>> - Object confirming deletion or error.

Example:

const { data, error } = await sqlClient.deleteDatabase(123);
if (data) {
  console.log(`Database ${data.id} deleted successfully`);
} else {
  console.error('Failed to delete database', error);
}

getDatabase

Retrieves a database by its Name.

Parameters:

  • name: string - Name of the database to retrieve.
  • options?: AzionClientOptions - Optional parameters for the retrieval.

Returns:

  • Promise<AzionDatabaseResponse<AzionDatabase>> - The retrieved database object or error.

Example:

const { data, error } = await sqlClient.getDatabase('my-db');
if (data) {
  console.log(`Retrieved database: ${data.name}`);
} else {
  console.error('Database not found', error);
}

getDatabases

Retrieves a list of databases with optional filtering and pagination.

Parameters:

  • params?: AzionDatabaseCollectionOptions - Optional parameters for filtering and pagination.
  • options?: AzionClientOptions - Optional parameters for the retrieval.

Returns:

  • Promise<AzionDatabaseResponse<AzionDatabaseCollections>> - Array of database objects or error.

Example:

const { data: allDatabases, error } = await sqlClient.getDatabases({ page: 1, page_size: 10, search: 'test' });
if (allDatabases) {
  console.log(`Retrieved ${allDatabases.count} databases`);
  allDatabases.results.forEach((db) => console.log(`- ${db.name} (ID: ${db.id})`));
} else {
  console.error('Failed to retrieve databases', error);
}

useQuery

Executes a query on a specific database.

Parameters:

  • name: string - Name of the database to query.
  • statements: string[] - Array of SQL statements to execute.
  • options?: AzionClientOptions - Optional parameters for the query.

Returns:

  • Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>> - Query result object or error.

Example:

const { data, error } = await sqlClient.query('my-db', ['SELECT * FROM users']);
if (data) {
  console.log(`Query executed. Rows returned: ${data.rows.length}`);
} else {
  console.error('Query execution failed', error);
}

useExecute

Executes a set of SQL statements on a specific database.

Parameters:

  • name: string - Name of the database to execute the statements on.
  • statements: string[] - Array of SQL statements to execute.
  • options?: AzionClientOptions - Optional parameters for the execution.

Returns:

  • Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>> - Execution result object or error.

Example:

const { data, error } = await sqlClient.execute('my-db', ['INSERT INTO users (name) VALUES ("John")']);
if (data) {
  console.log('Executed with success');
} else {
  console.error('Execution failed', error);
}

createClient

Creates an SQL client with methods to interact with Azion Edge SQL databases.

Parameters:

  • config?: Partial<{ token: string; options?: AzionClientOptions }> - Configuration options for the SQL client.

Returns:

  • AzionSQLClient - An object with methods to interact with SQL databases.

Types

Types

ClientConfig

Configuration options for the SQL client.

  • token?: string - Your Azion API token.
  • options?: AzionClientOptions - Optional parameters for the client configuration.

AzionSQLClient

An object with methods to interact with SQL databases.

  • createDatabase: (name: string) => Promise<AzionDatabaseResponse<AzionDatabase>>
  • deleteDatabase: (id: number) => Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>
  • getDatabase: (name: string) => Promise<AzionDatabaseResponse<AzionDatabase>>
  • getDatabases: (params?: AzionDatabaseCollectionOptions) => Promise<AzionDatabaseResponse<AzionDatabaseCollections>>
  • useQuery: (name: string, statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>
  • useExecute: (name: string, statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseExecutionResponse>>

AzionDatabase

The database object.

  • id: number
  • name: string
  • clientId: string
  • status: string
  • createdAt: string
  • updatedAt: string
  • deletedAt: string | null
  • query: (statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>
  • execute: (statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseExecutionResponse>>
  • getTables: (options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>

AzionDatabaseResponse<T>

The response object from a database operation.

  • data?: T
  • error?: { message: string, operation: string }

QueryResult

  • state: string
  • columns: string[]
  • statement: string
  • rows: (number | string)[][]

AzionClientOptions

Optional parameters for the client configuration.

  • debug?: boolean
  • force?: boolean

AzionDatabaseCollectionOptions

Optional parameters for filtering and pagination.

  • ordering?: string
  • page?: number
  • page_size?: number
  • search?: string

AzionDatabaseQueryResponse

The response object from a query execution.

  • state: 'executed' | 'pending' | 'executed-runtime' | 'failed'
  • data: QueryResult[]
  • toObject?: () => JsonObjectQueryExecutionResponse

AzionDatabaseExecutionResponse

The response object from a query execution.

  • state: 'executed' | 'pending' | 'executed-runtime' | 'failed'
  • data: QueryResult[]
  • toObject?: () => JsonObjectQueryExecutionResponse

AzionQueryExecutionParams

Parameters for query execution.

  • statements: string[]
  • params?: (AzionQueryParams | Record<string, AzionQueryParams>)[]

AzionQueryParams

Query parameters.

  • string | number | boolean | null

Contributing

Feel free to submit issues or pull requests to improve the functionality or documentation.