Macro for implementing database adapter modules.

This macro provides the foundation for creating database adapter modules by setting up the necessary behavior implementation, generating helper functions, and providing a unified table/2 interface that combines introspection and compilation.

When you use Drops.SQL.Database, the macro automatically:

1. Sets up the Drops.SQL.Database behavior
2. Generates helper functions for accessing adapter configuration
3. Creates a table/2 function that orchestrates introspection and compilation
4. Requires you to implement the introspect_table/2 callback

Options

• :adapter - The adapter identifier atom (e.g., :postgres, :sqlite, :mysql)
• :compiler - The compiler module to use for processing AST (e.g., Drops.SQL.Compilers.Postgres)

Generated Functions

The macro generates these functions in your adapter module:

• opts/0 - Returns the complete adapter configuration as a keyword list
• adapter/0 - Returns the adapter identifier atom for easy access
• table/2 - High-level interface that introspects and compiles a table in one call

Usage Example

defmodule Drops.SQL.MyDatabase do
  use Drops.SQL.Database,
    adapter: :my_database,
    compiler: Drops.SQL.Compilers.MyDatabase

  @impl true
  def introspect_table(table_name, repo) do
    # Your database-specific introspection logic
    with {:ok, raw_data} <- query_system_tables(table_name, repo) do
      {:ok, build_ast(raw_data)}
    end
  end

  # Private helper functions for introspection
  defp query_system_tables(table_name, repo) do
    # Implementation specific to your database
  end

  defp build_ast(raw_data) do
    # Convert raw database data to AST format
  end
end

Implementation Requirements

After using this macro, you must implement:

• introspect_table/2 callback - The core introspection logic for your database

Generated table/2 Function

The generated table/2 function provides a complete introspection and compilation pipeline:

{:ok, table} = MyAdapter.table("users", MyApp.Repo)
# This internally calls:
# 1. MyAdapter.introspect_table("users", MyApp.Repo)
# 2. Drops.SQL.Database.compile_table(compiler, ast, opts)

@spec compile_table(module(), table(), map()) ::
  {:ok, Drops.SQL.Database.Table.t()} | {:error, term()}

Compiles a database table AST into a structured Table struct.

This function processes the raw AST (Abstract Syntax Tree) returned by database adapter introspection through the specified compiler module to produce a fully structured Drops.SQL.Database.Table struct with normalized data types and metadata.

This is typically called internally by adapter modules after introspection, but can be used directly if you have a pre-built AST from another source.

Parameters

• compiler - The compiler module to use for processing the AST (e.g., Drops.SQL.Compilers.Postgres)
• ast - The table AST returned by introspection, following the table() type specification
• opts - Compilation options map, typically includes adapter information and other metadata

Returns

• {:ok, Table.t()} - Successfully compiled table with normalized types and metadata
• {:error, term()} - Error during compilation, such as invalid AST structure or compiler issues

Examples

# Typically called internally by adapter modules
ast = {:table, {{:identifier, "users"}, columns, foreign_keys, indices}}
{:ok, table} = Drops.SQL.Database.compile_table(
  Drops.SQL.Compilers.Postgres,
  ast,
  %{adapter: :postgres}
)

# The resulting table struct contains normalized data
table.name          # :users (atom)
table.columns       # [%Column{...}] with normalized types
table.primary_key   # %PrimaryKey{...}

AST Structure

The AST must follow the table() type specification:

• {:table, {name, columns, foreign_keys, indices}}
• Where each component follows its respective AST type definition

Compiler Requirements

The compiler module must implement a process/2 function that accepts the AST and options, returning either a Table.t() struct or an error.

@spec list_tables(module()) :: {:ok, [String.t()]} | {:error, term()}

Lists all tables in the database.

This function automatically detects the database adapter from the repository configuration and delegates to the appropriate adapter module to retrieve a list of all user-defined tables in the database.

Parameters

• repo - The Ecto repository module configured for your database

Returns

• {:ok, [String.t()]} - Successfully retrieved list of table names
• {:error, {:unsupported_adapter, module()}} - Repository uses unsupported adapter
• {:error, term()} - Database error during query execution

Examples

# List all tables in the database
{:ok, tables} = Drops.SQL.Database.list_tables(MyApp.Repo)
# => {:ok, ["users", "posts", "comments"]}

# Handle errors
case Drops.SQL.Database.list_tables(MyApp.Repo) do
  {:ok, tables} ->
    IO.puts("Found #{length(tables)} tables")
  {:error, reason} ->
    IO.puts("Error: #{inspect(reason)}")
end

Supported Adapters

• PostgreSQL via Ecto.Adapters.Postgres
• SQLite via Ecto.Adapters.SQLite3

Implementation Notes

• Excludes system tables and migration tables
• Results are ordered alphabetically by table name
• Only returns actual tables, not views or other database objects

@spec table(String.t(), module()) ::
  {:ok, Drops.SQL.Database.Table.t()} | {:error, term()}

Introspects and compiles a database table into a structured representation.

This is the main interface for database table introspection. It automatically detects the database adapter from the repository configuration and delegates to the appropriate adapter module for introspection and compilation.

The function performs two main operations:

1. Introspects the table structure using the database-specific adapter
2. Compiles the raw AST into a structured Drops.SQL.Database.Table struct

Parameters

• name - The name of the database table to introspect (as a string)
• repo - The Ecto repository module configured for your database

Returns

• {:ok, Table.t()} - Successfully compiled table structure with all metadata
• {:error, {:unsupported_adapter, module()}} - Repository uses unsupported adapter
• {:error, term()} - Database error during introspection or compilation error

Examples

# Introspect a users table
{:ok, table} = Drops.SQL.Database.table("users", MyApp.Repo)

# Access table metadata
table.name          # :users (converted to atom)
table.columns       # [%Column{name: :id, type: :integer, ...}, ...]
table.primary_key   # %PrimaryKey{fields: [:id]}
table.foreign_keys  # [%ForeignKey{field: :user_id, ...}, ...]
table.indices       # [%Index{name: :users_email_index, ...}, ...]

# Handle errors
case Drops.SQL.Database.table("nonexistent", MyApp.Repo) do
  {:ok, result} ->
    IO.puts("Found table: #{result.name}")
  {:error, reason} ->
    IO.puts("Error: #{inspect(reason)}")
end

Supported Adapters

• PostgreSQL via Ecto.Adapters.Postgres
• SQLite via Ecto.Adapters.SQLite3

Error Cases

The function can return errors in several scenarios:

• Unsupported database adapter
• Table does not exist in the database
• Database connection issues
• Permission issues accessing table metadata