view release on metacpan or  search on metacpan

docs/tr/AmberDB_Veritabani_Sistemi.md  view on Meta::CPAN

1. **Fiziksel Dosya Tabanlı Şema (Önerilen):**  
   Tablo şemaları `dbstore/schema/<tablo_adi>.table` dosyasına yerleştirilir. AmberDB ilk erişimde bu dosyayı otomatik olarak okur ve ayrıştırır.

2. **Bellek İçi Dinamik Şema (Programmatic / In-Memory):**  
   Disk dosyasına gerek kalmadan doğrudan `$adb->table_attr("tablo_adi", { ... })` metoduyla çalışma zamanında tanımlanır.

3. **Yüklü Şemayı Okuma (`table_info`):**  
   Tanımlı bir tablonun tüm şema konfigürasyonunu bellekten veya diskten hash referansı olarak almak için `$adb->table_info($tablo_adi)` kullanılır:
   ```perl
   my $schema = $adb->table_info("catalog_product");
   print "Tablo Adı: $schema->{name}\n";
   print "Arama Blokları: " . join(", ", @{ $schema->{search_block} || [] }) . "\n";
   ```

> [!IMPORTANT]
> **Şema Dosyaları (`.table` ve `.dbase`) Doğal Perl Kodudur (Hash Reference)**  
> AmberDB'de `.table` ve `.dbase` dosyaları JSON veya YAML değil, doğrudan Perl sözdizimiyle (`{ ... }`) yazılmış doğal Perl hash referansı yapılarıdır. Motor bu dosyaları çalışma zamanında Perl'in yerel `do` ifadesi ile dinamik olar...
>
> * **Sözdizimi Hatası Koruması:** Dosyada eksik virgül (`,`), kapatılmamış parantez (`}` veya `]`), hatalı tırnak işareti veya geçersiz bir Perl karakteri bulunursa `do` işlemi `undef` döner ve motor şemayı **kesinlikle yükleyemez** ...
> * **Doğrulama İpucu:** Şema dosyalarınızı kaydettikten sonra terminalden `perl -c dbstore/schema/tablo.table` komutuyla derleme kontrolü yaparak sözdizimi hatalarını anında görebilirsiniz.

### 10.3 Şema Dosyası Eşleşme Kuralları

AmberDB, tablo adını ayrıştırarak hangi şema dosyasını ve veritabanı ayarlarını yükleyeceğini otomatik belirler:

* **Veritabanı Ön Eki:** Tablo adında ilk alt çizgiden (`_`) önceki kısım veritabanı / mantıksal grup adıdır.
* **Şema Dosyası Eşleşmesi:** Örneğin `catalog_product` tablosunun şeması `dbstore/schema/catalog_product.table` dosyasında, grup ayarları ise `dbstore/schema/catalog.dbase` dosyasında saklanır.

### 10.4 Örnek Tablo Şeması (`catalog_product.table`)

Aşağıda e-ticaret ürün kataloğu için kapsamlı bir `.table` şema örneği verilmiştir:

```perl
# dbstore/schema/catalog_product.table
{
    name         => "Ürün Kataloğu",
    id_type      => "num",                  
    record_index => 1,                      
    match_block  => [ 1, 2, 3, 11 ],        
    search_block => [ 4, 5, 7, 9 ],         
    sort_block   => [ 4, { blk => 10, type => 'num' } ], 
    facet_block  => [ 1, 2, 3, 11 ],        
    seo_block    => [ 2, 4 ],               
    
    use_facet    => 1,                      
    facet_rules  => [ [ 11, "eq", 1 ] ],    
    use_junk     => 1,                      
    junk_rules   => [ [ 11, "eq", 0 ] ],    
    use_cache    => 1,                      
    cache_ttl    => 3600,                   
    keep_deleted => 1,                      
    log_owner    => 1,                      
    min_char     => 2,                      
    
    blocks => [
        { id => "id",           name => "Ürün ID",     type => "auto_id", input => "hidden" },
        { id => "category_id",  name => "Kategori",    type => "text",    input => "select",   rdbm => "catalog_category;2" },
        { id => "brand_id",     name => "Marka",       type => "text",    input => "select",   rdbm => "catalog_brand;2" },
        { id => "author_id",    name => "Yazar",       type => "text",    input => "text" },
        { id => "title",        name => "Ürün Adı",    type => "text",    input => "text",     valid => "not_null" },
        { id => "subtitle",     name => "Alt Başlık",  type => "text",    input => "text" },
        { id => "supplier",     name => "Tedarikçi",   type => "text",    input => "text" },
        { id => "description",  name => "Açıklama",    type => "html",    input => "textarea" },
        { id => "stock",        name => "Stok Adedi",  type => "num",     input => "text" },
        { id => "barcode",      name => "Barkod",      type => "text",    input => "text" },
        { id => "price",        name => "Fiyat",       type => "num",     input => "text" },
        { id => "status",       name => "Satış Durumu",type => "option",  input => "select",   option => "1:Satışta,0:Pasif" },
    ],
}
```

### 10.5 Şema Parametreleri ve Konfigürasyon Referansı (Tablo Düzeyi)

Aşağıdaki tablo, bir `.table` dosyasında kullanılabilecek tüm üst düzey parametreleri, veri tiplerini, varsayılan değerlerini ve geriye dönük uyumluluk (eski sistem) karşılıklarını listeler:

| Parametre | Tip | Varsayılan | Eski / Alternatif Adı | Açıklama |
| :--- | :--- | :--- | :--- | :--- |
| `name` | `string` | `"Tablo"` | — | Tablonun insan tarafından okunabilir adı/başlığı. |
| `id_type` | `string` | `"num"` | — | Birincil anahtar tipi: `"num"` (64-bit tamsayı) veya `"ascii"` (maks 8 bayt). |
| `record_index` | `0 / 1` | `0` | `readall` | `1` ise `.inx` birincil indeksini, `table_count`, `table_lastid` ve otomatik sayaç desteğini aktif eder. |
| `search_block` | `ARRAY` | `[]` | — | `.src` tam metin arama (inverted keyword) indeksine dahil edilecek blok numaraları. |
| `match_block` | `ARRAY` | `[]` | `fields` | `.fld` birebir eşleşme / filtrelenmiş okuma indeksine dahil edilecek blok numaraları. |
| `sort_block` | `ARRAY` | `[]` | — | `.srt` önceden sıralanmış binary ID indeksleri oluşturulacak bloklar (`[ 4, { blk => 10, type => 'num' } ]`). |
| `facet_block` | `ARRAY` | `[]` | `filter_block` | `.fac` çok boyutlu dinamik kategori/ürün filtreleme indeksine dahil edilecek bloklar. |
| `seo_block` | `ARRAY` | `[]` | `rwlink` | `.rwt` otomatik iki yönlü SEO slug (URL rewrite) üretimi için birleştirilecek bloklar. |
| `use_facet` | `0 / 1` | `0` | — | Tabloda facet sayım motorunu ve `field_fltkeys` / `facet_menu` altyapısını aktif eder. |
| `facet_rules` | `ARRAY` | `[]` | — | Facet menüsünde sadece belirli şarta uyan (örn: stokta olan) kayıtları saymak için filtre kuralları. |
| `use_junk` | `0 / 1` | `0` | — | Pasif/arşiv kayıtları ana tablodan ayırarak iki katmanlı (Hot/Cold) indeksleme sağlar. |
| `junk_rules` | `ARRAY` | `[]` | — | Hangi kayıtların otomatik olarak Junk katmanına (`.jinx`, `.jsrc`, `.jfld`) taşınacağını belirleyen kurallar. |
| `use_cache` | `0 / 1 / 2` | `0` | `usecache` | `0`: Kapalı, `1`: Soft (.inx meta önbelleği), `2`: Hard (Tam RAM-Disk aynası). |
| `cache_ttl` | `integer` | `3600` | — | Tabloya özgü RAM önbellek geçerlilik süresi (saniye). |
| `keep_deleted` | `0 / 1` | `0` | `nodelete` | Silinen kayıtları yok etmek yerine `.del` arşiv dosyasında saklar (Soft-delete). |
| `log_owner` | `0 / 1` | `0` | `authority` | Kaydı ekleyen, düzenleyen ve silen kullanıcıları `.aut` denetim izinde saklar. |
| `use_alias` | `0 / 1` | `0` | `uselnk` | Kayıt birleştirmeleri ve eski ID yönlendirmeleri için `.lnk` alias tablosunu aktif eder. |
| `use_counter` | `0 / 1` | `0` | `usecnt` | `.cnt` dosyasında kayıt okuma/görüntülenme sayaçlarını otomatik artırır. |
| `parent_table` | `string` | `""` | — | Dikey bölümlemede üst tablo adı. Bağlı tablo aynı ID'yi paylaşarak ana tabloyu hafif tutar. |
| `force` | `0 / 1` | `0` | — | `1` ise `insert_id` çağrısında kayıt zaten varsa hata vermek yerine üstüne yazar (Replace modu). |
| `min_char` | `integer` | `2` | `minchar` | Arama indeksine (`.src`) alınacak kelimeler için asgari karakter uzunluğu (1, 2 veya 3). |
| `stop_word` | `string` | `""` | `nextkey` | Arama indeksine dahil edilmeyecek durak kelimeler (örn: `"bu ve ile için de da"`). |
| `repeat_ids` | `integer` | `undef` | — | Tekrarlayan alt blokların ID listesinin otomatik toplanacağı hedef blok indeksi. |
| `repeat_start` | `integer` | `undef` | — | Dinamik değişken alt elemanların (sipariş kalemleri vb.) başladığı blok indeksi. |
| `view_block` | `ARRAY` | `[]` | — | Arayüz (Dbapp / CMS) listeleme ekranında gösterilecek öncelikli blok numaraları. |
| `use_menu` | `0 / 1` | `1` | — | Arayüz yönetim panelinde tablo için menü sekmesi gösterilip gösterilmeyeceği. |
| `no_transact` | `0 / 1` | `0` | — | `1` ise tablo transaction hata zincirinden ve otomatik rollback işleminden muaf tutulur. |

### 10.6 Blok (Alan) Nitelikleri, Veri Tipleri, Giriş Bileşenleri ve Doğrulama Referansı

Şema içerisindeki `blocks` dizisinde her bir veri alanı (sütun) için aşağıdaki nitelikler tanımlanabilir:

#### 1. Temel Blok Nitelikleri

| Nitelik | Tip | Açıklama | Örnek |
| :--- | :--- | :--- | :--- |
| `id` | `string` | Alanın programatik benzersiz anahtar adı | `id => "email"` |
| `name` | `string` | Formlarda ve arayüzlerde görünen etiket adı | `name => "E-Posta Adresi"` |
| `type` | `string` | Alanın veri saklama ve indeksleme tipi | `type => "text"` |
| `input` | `string` | HTML/UI Form giriÅŸ bileÅŸeni tipi | `input => "select"` |
| `valid` | `string` | Otomatik veri doğrulama kuralı | `valid => "not_null;email"` |
| `option` | `string` | `select`/`radio`/`checkbox` için hazır seçenekler listesi | `option => "1:Aktif,0:Pasif"` |
| `rdbm` | `string / HASH`| BaÅŸka bir tablodan ID $\rightarrow$ Metin eÅŸleme | `rdbm => "catalog_category;2"` |
| `extend` | `HASH` | 1:1 dikey geniÅŸleme tablosu baÄŸlama | `extend => { table => "catalog_price", join => "id" }` |

#### 2. Desteklenen Alan Tipleri (`type`)

| Tip (`type`) | Tanım | Açıklama ve Kullanım |
| :--- | :--- | :--- |
| `auto_id` | Otomatik ID | Otomatik artan 64-bit birincil anahtar (Blok 0 için zorunludur). |
| `text` | Metin | Standart tek satırlı UTF-8 metin veya alfanümerik dize. |
| `tinytext` | Kısa Metin | Kısa etiketler, kodlar veya bayraklar için optimize edilmiş metin. |
| `number` | Sayı | Sayısal değer (tamsayı veya ondalıklı para/miktar; `.srt` indeksinde sayısal olarak sıralanır). |
| `email` | E-posta | E-posta adresi formatındaki alanlar. |
| `ascii` | ASCII Metin | Yalnızca ASCII karakterler içeren kullanıcı adı, kod vb. veriler. |
| `password` | Şifre | Tek yönlü tuzlu hash olarak saklanan şifre alanları. |
| `date_short` | Kısa Tarih | `YYYY-MM-DD` veya `YYYYMMDD` formatında kısa tarih dizesi. |
| `date_long` | Uzun Tarih | `YYYY-MM-DD HH:MM:SS` formatında zaman damgalı uzun tarih dizesi. |
| `html` | Zengin HTML | HTML gövdeleri (arama indeksine alınırken etiketler otomatik temizlenir). |
| `array` | Liste (Array) | İç içe dizi referansı (`[ "a", "b", "c" ]` veya virgüllü değerler). |
| `hash` | Liste (Hash) | İç içe sözlük referansı (`{ k1 => "v1", k2 => "v2" }`). |
| `binary` | Binary | Ham ikili (binary) veya pack edilmiÅŸ bayt verisi. |
| `base64` | Base64 | Base64 formatında kodlanmış veri blokları. |
| `extend` | Harici Tablo | 1:1 dikey genişleme tablosu (aynı ID'yi paylaşır). |
| `tables` | Birleşik Tablolar | Çoklu tablo ilişkileri ve agregasyon blokları. |
| `loop` / `repeat` | Son Blok Döngüsü | Değişken sayıda tekrarlayan alt döküman blokları (`repeat_start` ile kullanılır). |

#### 3. Form GiriÅŸ BileÅŸenleri (`input`)

| Giriş Bileşeni (`input`) | UI Karşılığı | Açıklama |
| :--- | :--- | :--- |
| `text` | Text | Standart tek satırlık metin kutusu `<input type="text">`. |
| `textarea` | Textarea | Çok satırlı düz metin alanı `<textarea>`. |
| `summernote` | Summernote | Zengin WYSIWYG HTML editörü (açıklama ve makale gövdeleri için). |
| `select` | Select | Tekli açılır liste kutusu `<select>`. |
| `checkbox` | Checkbox | Çoklu seçim onay kutusu `<input type="checkbox">`. |
| `radio` | Radio | Tekli seçim radyo butonu `<input type="radio">`. |
| `file` | File | Dosya veya görsel yükleme bileşeni `<input type="file">`. |
| `hidden` | Hidden | Gizli form alanı `<input type="hidden">` (ID alanları için). |
| `email` | Email | E-posta giriÅŸi `<input type="email">`. |
| `ascii` | Kullanıcı / ASCII | Kullanıcı adı veya kod girişi için ASCII kısıtlamalı metin kutusu. |
| `number` | Numara | Sayısal giriş kutusu `<input type="number">`. |
| `date` | Tarih | Tarih seçici bileşeni `<input type="date">`. |
| `password` | Password | Şifrelenmiş giriş alanı `<input type="password">`. |
| `search_block` | Search | Arama destekli dinamik filtre giriÅŸ kutusu. |
| `selectbyfind` | SelectByFind | Arama ile dinamik veri getiren ilişkili seçim kutusu. |
| `selectbylist` | SelectByList | Liste üzerinden çoklu eleman seçimine izin veren bileşen. |

#### 4. Otomatik Doğrulama Kuralları (`valid`)

Birden fazla doğrulama kuralı noktalı virgül (`;`) ile zincirlenebilir (örn: `valid => "not_null;email"`):

| Doğrulama Kuralı (`valid`) | Tanım | Kontrol ve Davranış |
| :--- | :--- | :--- |
| `none` | Doğrulama Yok | Herhangi bir kural uygulanmaz (varsayılan). |
| `not_null` | Boş Olamaz | Alanın boş (`undef` veya `""`) geçilmesini engeller. |
| `unique` | Benzersiz | Değerin tabloda başka hiçbir kayıtta bulunmadığını doğrular. |
| `email` | E-posta | Geçerli bir RFC e-posta deseni kontrolü yapar. |
| `telefon` | Telefon | Geçerli sabit/GSM telefon numarası formatı kontrolü yapar. |
| `ascii` | ASCII | Değerin yalnızca ASCII karakterler içermesini zorunlu kılar. |
| `regex` | Regex | Özel tanımlı düzenli ifade desenine uyumu denetler. |
| `auto_num` | Otomatik Sayı | Değeri otomatik artan sayı olarak üretir. |
| `auto_pass` | Otomatik Şifre | Rastgele güvenli şifre üretir ve tuzlu hash olarak kaydeder. |
| `auto_date` | Otomatik Tarih | O anki sistem tarih/zaman damgasını otomatik atar. |
| `auto_str` | Hazır Metin | Önceden tanımlı şablon metnini otomatik uygular. |

### 10.7 CRUD İşlemlerinde Şemanın Rolü

Bir kayıt `insert_id` veya `modify_id` ile kaydedilirken geçirilen dizi argümanları blok indeksleriyle birebir eşleşir. Motor bu tek işlemde şemaya bakarak veriyi `.db` ana dosyasına yazar, `.inx` listesini günceller ve ilgili tüm `.fld`, ...

### 10.8 Çalışma Zamanında Dinamik Şema Manipülasyonu (`table_attr`)

AmberDB şemaları statik değildir. Veritabanını baştan oluşturmaya veya migration çalıştırmaya gerek kalmadan çalışma zamanında (runtime) dinamik olarak güncellenebilir:

```perl
$adb->table_attr("catalog_product", { search_block => [ 4, 9 ] });
```

### 10.9 Dinamik GeniÅŸleyen Tablolar ve Tekrarlayan Bloklar (`repeat_ids` & `repeat_start`)

AmberDB, sabit sütun sınırlarını aşarak tek bir ana döküman kaydının sonuna değişken sayıda alt eleman (sipariş kalemleri vb.) eklenmesine olanak tanır.

```perl
# dbstore/schema/order_active.table
{
    name         => "Aktif SipariÅŸler",
    record_index => 1,
    match_block  => [ 1, 2, 12, 14 ],
    keep_deleted => 1,
    log_owner    => 1,
    repeat_ids   => 12,
    repeat_start => 15,

    blocks => [
        { id => "id",                name => "ID",                   type => "auto_id" }, # 0
        { id => "member_id",         name => "Ãœye ID",               type => "text" },    # 1
        { id => "invoice_no",        name => "Fatura No",            type => "text" },    # 2
        { id => "amounts",           name => "Tutarlar",             type => "array" },   # 3
        { id => "timestamps",        name => "Tarihler",             type => "array" },   # 4
        { id => "status",            name => "Statü",                type => "option" },  # 5
        { id => "session_id",        name => "Session ID",           type => "text" },    # 6
        { id => "delivery_address",  name => "Teslim Adresi",        type => "array" },   # 7
        { id => "invoice_address",   name => "Fatura Adresi",        type => "array" },   # 8
        { id => "cargo",             name => "Kargo Bilgileri",      type => "array" },   # 9
        { id => "payment_info",      name => "Ödeme Tipi",           type => "array" },   # 10
        { id => "credit_card_info",  name => "Kredi Kartı Bilgileri",type => "array" },   # 11
        { id => "product_ids",       name => "Ürün Döngüsü",         type => "text" },    # 12 (repeat_ids)
        { id => "member_notes",      name => "Üye Notları",          type => "array" },   # 13
        { id => "gift_products",     name => "Hediye Ürünler",       type => "text" },    # 14
        { id => "products",          name => "Ürün Kalemleri",       type => "repeat" },  # 15 (repeat_start)
    ]
}
```

#### 2. Çalışma Mantığı ve Otomatik İndeksleme (`repeat_fields`)
Her `insert_id`, `modify_id`, `insert_list` veya `modify_list` çağrısında motor, `repeat_start` (15) ve sonrasındaki tüm değişken blokları otomatik olarak işler: