docs

Author: mstgnz

docs/api.md

@@ -1,239 +1,225 @@
-# API Documentation
+# SQLMapper API Documentation
 
-## Contents
+## Overview
+SQLMapper provides a comprehensive API for converting SQL schemas between different database systems. This document outlines the main components and their usage.
+
+## Table of Contents
 - [Parser API](#parser-api)
 - [Converter API](#converter-api)
-- [Migration API](#migration-api)
-- [Database API](#database-api)
-- [Helper Functions](#helper-functions)
+- [Schema API](#schema-api)
+- [Error Handling](#error-handling)
+- [Examples](#examples)
 
 ## Parser API
 
-### NewParser
-
-Creates a new 
+### Creating a Parser
 
 ```go
-func NewParser(dialect string) (Parser, error)
+parser := mysql.NewMySQL()    // For MySQL
+parser := postgres.NewPostgreSQL()  // For PostgreSQL
+parser := sqlite.NewSQLite()  // For SQLite
+parser := oracle.NewOracle()  // For Oracle
+parser := sqlserver.NewSQLServer()  // For SQL Server
 ```
 
-**Parameters:**
-- `dialect`: Database dialect ("mysql", "postgres", "sqlite", "oracle", "sqlserver")
-
-**Return Values:**
-- `Parser`: Object implementing the Parser interface
-- `error`: In case of error
-
-### Parse
-
-Parses SQL dump file.
+Each parser implements the `Parser` interface:
 
 ```go
-func (p *Parser) Parse(sql string) (*Entity, error)
+type Parser interface {
+    Parse(content string) (*Schema, error)
+    Generate(schema *Schema) (string, error)
+}
 ```
 
-**Parameters:**
-- `sql`: SQL dump text to parse
-
-**Return Values:**
-- `*Entity`: Parsed data structure
-- `error`: In case of error
-
-## Converter API
-
-### Convert
-
-Converts a database schema to another database format.
+### Parsing SQL
 
 ```go
-func Convert(sql, sourceDialect, targetDialect string) (string, error)
+// Parse SQL content into a schema
+schema, err := parser.Parse(sqlContent)
+if err != nil {
+    log.Fatal(err)
+}
 ```
 
-**Parameters:**
-- `sql`: SQL text to convert
-- `sourceDialect`: Source database dialect
-- `targetDialect`: Target database dialect
-
-**Return Values:**
-- `string`: Converted SQL text
-- `error`: In case of error
-
-### ConvertEntity
-
-Converts Entity structure to SQL.
+### Generating SQL
 
 ```go
-func (p *Parser) ConvertEntity(entity *Entity) (string, error)
+// Generate SQL from a schema
+sql, err := parser.Generate(schema)
+if err != nil {
+    log.Fatal(err)
+}
 ```
 
-**Parameters:**
-- `entity`: Entity structure to convert
-
-**Return Values:**
-- `string`: Generated SQL text
-- `error`: In case of error
-
-## Migration API
-
-### NewMigrationManager
+## Schema API
 
-Creates a new migration manager.
+The Schema structure represents a complete database schema:
 
 ```go
-func NewMigrationManager(db *sql.DB) *MigrationManager
+type Schema struct {
+    Name        string
+    Tables      []Table
+    Views       []View
+    Triggers    []Trigger
+    Sequences   []Sequence
+    Functions   []Function
+    Procedures  []Procedure
+    // ... other fields
+}
 ```
 
-**Parameters:**
-- `db`: Database connection
-
-### Apply
-
-Applies migrations.
+### Table Structure
 
 ```go
-func (m *MigrationManager) Apply(ctx context.Context) error
+type Table struct {
+    Name        string
+    Schema      string
+    Columns     []Column
+    Indexes     []Index
+    Constraints []Constraint
+    Comment     string
+}
 ```
 
-**Parameters:**
-- `ctx`: Context object
-
-**Return Values:**
-- `error`: In case of error
-
-### Rollback
-
-Rolls back the last migration.
+### Column Structure
 
 ```go
-func (m *MigrationManager) Rollback(ctx context.Context) error
+type Column struct {
+    Name          string
+    DataType      string
+    Length        int
+    Scale         int
+    IsNullable    bool
+    DefaultValue  string
+    AutoIncrement bool
+    IsPrimaryKey  bool
+    IsUnique      bool
+    Comment       string
+}
 ```
 
-**Parameters:**
-- `ctx`: Context object
-
-**Return Values:**
-- `error`: In case of error
+## Error Handling
 
-## Database API
-
-### NewConnection
-
-Creates a new database connection.
+SQLMapper provides specific error types for different scenarios:
 
 ```go
-func NewConnection(config *Config) (*sql.DB, error)
+var (
+    ErrEmptyContent     = errors.New("empty content")
+    ErrInvalidSQL       = errors.New("invalid SQL syntax")
+    ErrUnsupportedType  = errors.New("unsupported data type")
+    ErrParserNotFound   = errors.New("parser not found for database type")
+)
 ```
 
-**Parameters:**
-- `config`: Database configuration
-
-**Return Values:**
-- `*sql.DB`: Database connection
-- `error`: In case of error
+## Examples
 
-### Config Structure
+### Basic Usage
 
 ```go
-type Config struct {
-    Driver   string
-    Host     string
-    Port     int
-    Database string
-    Username string
-    Password string
-    SSLMode  string
-    Options  map[string]string
-}
-```
-
-## Helper Functions
-
-### ValidateSQL
-
-Validates SQL text.
+package main
 
-```go
-func ValidateSQL(sql string) error
-```
+import (
+    "fmt"
+    "github.com/mstgnz/sqlmapper/mysql"
+    "github.com/mstgnz/sqlmapper/postgres"
+)
 
-**Parameters:**
-- `sql`: SQL text to validate
+func main() {
+    // MySQL input
+    mysqlSQL := `
+    CREATE TABLE users (
+        id INT AUTO_INCREMENT PRIMARY KEY,
+        name VARCHAR(100) NOT NULL,
+        email VARCHAR(255) UNIQUE,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    );`
 
-**Return Values:**
-- `error`: In case of error
+    // Create parsers
+    mysqlParser := mysql.NewMySQL()
+    pgParser := postgres.NewPostgreSQL()
 
-### FormatSQL
+    // Parse MySQL
+    schema, err := mysqlParser.Parse(mysqlSQL)
+    if err != nil {
+        panic(err)
+    }
 
-Formats SQL text.
+    // Generate PostgreSQL
+    pgSQL, err := pgParser.Generate(schema)
+    if err != nil {
+        panic(err)
+    }
 
-```go
-func FormatSQL(sql string) string
+    fmt.Println(pgSQL)
+}
 ```
 
-**Parameters:**
-- `sql`: SQL text to format
-
-**Return Values:**
-- `string`: Formatted SQL text
+### CLI Usage
 
-## Error Types
+```bash
+# Convert MySQL to PostgreSQL
+sqlmapper --file=dump.sql --to=postgres
 
-```go
-var (
-    ErrInvalidDialect    = errors.New("invalid database dialect")
-    ErrParseFailure      = errors.New("SQL parse error")
-    ErrConversionFailure = errors.New("conversion error")
-    ErrConnectionFailure = errors.New("connection error")
-    ErrMigrationFailure  = errors.New("migration error")
-)
+# Convert PostgreSQL to SQLite
+sqlmapper --file=schema.sql --to=sqlite
 ```
 
-## Examples
-
-### Simple Conversion
+### Advanced Usage
 
 ```go
 package main
 
 import (
     "github.com/mstgnz/sqlmapper"
-    "log"
+    "github.com/mstgnz/sqlmapper/mysql"
 )
 
 func main() {
-    mysqlSQL := `CREATE TABLE users (
-        id INT PRIMARY KEY AUTO_INCREMENT,
-        name VARCHAR(100) NOT NULL
-    );`
+    parser := mysql.NewMySQL()
+    
+    // Parse complex schema
+    schema, err := parser.Parse(complexSQL)
+    if err != nil {
+        panic(err)
+    }
+
+    // Modify schema
+    for i, table := range schema.Tables {
+        // Add timestamps to all tables
+        schema.Tables[i].Columns = append(table.Columns,
+            sqlmapper.Column{
+                Name: "created_at",
+                DataType: "TIMESTAMP",
+                DefaultValue: "CURRENT_TIMESTAMP",
+            },
+            sqlmapper.Column{
+                Name: "updated_at",
+                DataType: "TIMESTAMP",
+                DefaultValue: "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP",
+            },
+        )
+    }
 
-    // Convert from MySQL to PostgreSQL
-    pgSQL, err := sqlmapper.Convert(mysqlSQL, "mysql", "postgres")
+    // Generate modified SQL
+    sql, err := parser.Generate(schema)
     if err != nil {
-        log.Fatal(err)
+        panic(err)
     }
-    
-    log.Println(pgSQL)
 }
 ```
 
-### Migration Usage
+## Best Practices
 
-```go
-package main
+1. Always check for errors when parsing and generating SQL
+2. Use appropriate parsers for source and target databases
+3. Validate schema modifications before generating SQL
+4. Handle database-specific features carefully
+5. Test conversions with sample data
 
-import (
-    "context"
-    "github.com/mstgnz/sqlmapper/migration"
-    "log"
-)
+## Limitations
 
-func main() {
-    // Create migration manager
-    manager := migration.NewMigrationManager(db)
-
-    // Apply migrations
-    err := manager.Apply(context.Background())
-    if err != nil {
-        log.Fatal(err)
-    }
-}
+- Some database-specific features may not be perfectly converted
+- Complex stored procedures might need manual adjustment
+- Custom data types may require special handling
+- Performance may vary with large schemas
+</rewritten_file>