AmberDB
view release on metacpan or search on metacpan
docs/TR.AmberDB_Veritabani_Sistemi.md view on Meta::CPAN
### 5.4 İndekssiz DoÄrudan Sorgulama ve Filtreleme
İkincil indeks dosyaları üretilmediÄi için sorgular doÄrudan `.db` veri akıÅı üzerinden sıralı tarama (`recs_scan`) ile yürütülür:
1. **Tüm Tabloyu Okuma ve Sayfalama (`read_all`):**
```perl
# Tüm kayıtlar veya sayfalama (offset => 0, limit => 10)
my ( $toplam, @kayitlar ) = $adb->read_all( 'items', { offset => 0, limit => 10 } );
# Sadece anahtar listesi alma
my @anahtarlar = $adb->read_all( 'items', { keys_only => 1 } );
# Bellek içi sıralama (Blok 3'e göre artan: -3, azalan: 3)
my @sirali = $adb->read_all( 'items', { sort => -3, keys_only => 1 } );
```
2. **Alana Göre EÅleÅtirme (`field_fetch`):**
```perl
# Blok 2: Kategori = 'Giyim' olanları getir
my @giyimler = $adb->field_fetch( 'catalog', 2, 'Giyim' );
# Ãoklu deÄer eÅleme (Blok 3: Renk in ['Mavi', 'Siyah'])
my ( $adet, @sonuclar ) = $adb->field_fetch( 'catalog', 3, [ 'Mavi', 'Siyah' ], { offset => 0, limit => 20, sort => -4 } );
```
3. **Tam Metin Arama (`search_table`):**
```perl
# Türkçe normalizasyonlu kelime araması (AND mantıÄı)
my @haberler = $adb->search_table( 'articles', 'türkiye ekonomi' );
# Alan filtresiyle birlikte arama (Blok 2: Kategori = 'Finans')
my ( $sayi, @filtrelenmis ) = $adb->search_table( 'articles', 'faiz', { offset => 0, limit => 10, filter => [ 2, 'Finans' ] } );
```
---
### 5.5 İÅlemler (Transactions - ACID DesteÄi)
Basit modda `transact_start`, `transact_error` ve `transact_end` ACID desteÄi tam olarak çalıÅır. Hata bildirildiÄinde (`transact_error`) veya bir iÅlem baÅarısız olduÄunda `transact_end` otomatik olarak geri alma (`rollback`) tetikler ve ...
```perl
$adb->transact_start();
eval {
$adb->insert_id( 'sessions', 'token_123', 'GeciciVeri', time() );
if ($hata_var) {
$adb->transact_error( 'sessions', 'Kritik islem hatasi' );
}
};
if ($@) {
$adb->transact_error( 'sessions', $@ );
}
my $txn = $adb->transact_end(); # Hata varsa otomatik rollback, yoksa commit
```
---
### 5.6 Günlük Sürekli Yedekleme Günlükleri (Daily Backup Logs - `recs_back`)
Basit mod Åemadan baÄımsız olduÄundan, **metin tabanlı sürekli denetim ve kurtarma akıÅı (`recs_back`)** basit modda da varsayılan olarak devrededir.
Basit modun düz dizin yapısı gereÄi ayrı bir `backup/` veya `YYYY/` alt klasörü oluÅturulmaz; yapılan her `insert_id` (`add`), `update_id` (`edit`) ve `delete_id` (`del`) iÅlemi doÄrudan tablolarla aynı dizinde bulunan **`$dbase_dir/YYYY-...
```text
2026-08-31 14:30:00 admin add sessions sess_token_99999 Aktif\x1f192.168.1.50
2026-08-31 14:31:15 admin edit sessions sess_token_99999 Kapali\x1f192.168.1.50
2026-08-31 14:32:00 admin del sessions sess_token_99999
```
- İstenirse `cfg => { no_backup => 1 }` veya `$adb->config(no_backup => 1)` ile yedekleme günlükleri devre dıÅı bırakılabilir.
- Ãzel bir yedek dizini tanımlanmak istendiÄinde `path => { backup_dir => "/harici/yedek/yolu" }` verilebilir.
---
### 5.7 Basit Modda RAM-Disk Mimarisi ve Ãnbellekleme
AmberDB standart modda RAM-disk hızlandırmasını Åemadaki `use_ramdisk => 2` kuralı ile yönetir.
**Basit modda ise RAM-disk kullanımı çok daha doÄrudan ve esnektir:**
Basit mod Åemaya ihtiyaç duymadıÄından, yüksek performanslı bir bellek önbelleÄi / geçici oturum deposu oluÅturmak için ikinci bir AmberDB basit nesnesi doÄrudan RAM-disk yoluna baÄlanır:
```perl
# 1. Kalıcı disk nesnesi (Kalıcı veriler için)
my $db_kalici = AmberDB->new(
path => { dbase_dir => "/var/data/eticaret/dbstore/table" },
cfg => { use_simple => 1 },
);
# 2. RAM-Disk nesnesi (Sıfır gecikmeli hızlı oturum/önbellek tabloları için)
# (Linux: /dev/shm veya tmpfs, Windows: ImDisk, macOS: APFS RAM-Disk /Volumes/AmberDB_RAM)
my $db_ramdisk = AmberDB->new(
path => { dbase_dir => "/dev/shm/amberdb_cache" },
cfg => { use_simple => 1, no_backup => 1 }, # Ãnbellek için yedekleme kapatılabilir
);
# RAM üzerinde nanosaniye hızında oturum okuma/yazma:
$db_ramdisk->insert_id( "oturumlar", $session_token, $user_id, time() );
my @oturum = $db_ramdisk->read_id( "oturumlar", $session_token );
```
Bu çift nesneli mimari sayesinde:
- RAM-disk üzerindeki tablolar disk I/O darboÄazına takılmadan bellek hızında çalıÅır.
- Kalıcı tablolar ana depolama alanında güvenle tutulmaya devam eder.
- Åema dosyası hazırlama zorunluluÄu olmadan saniyeler içinde dinamik önbellek tabloları açılabilir.
---
### 5.8 Basit Mod: Yetenekler ve Kısıtlamalar KarÅılaÅtırması
| Ãzellik / Mekanizma | Standart Mod (`use_simple => 0`) | Basit Mod (`use_simple => 1`) |
| :--- | :---: | :---: |
| **Åema Dosyaları (`.table`, `.dbase`)** | Zorunlu / Kullanılır | Yok / Åemasız |
| **Ãzel ve Uzun ID'ler (UUID, E-posta, vb.)** | 8 Bayt / ASCII Kısıtlı | **Tamamen Serbest** |
| **Tekil CRUD (`insert_id`, `read_id`, vb.)** | $O(1)$ | **$O(1)$ (Maksimum Hız)** |
| **Toplu İÅlemler (`insert_list`, vb.)** | Desteklenir | Desteklenir |
| **Tüm Tablo Okuma (`read_all`)** | `.inx` veya doÄrudan | DoÄrudan Dosya Taraması |
| **Sayfalama (`start`/`limit`) ve `keys_only`** | Desteklenir | Desteklenir |
| **Bellek İçi Sıralama (`sort => 2`)** | Desteklenir | Desteklenir |
| **Alana Göre Filtre (`field_fetch`)** | `.fld` İndeksli $O(1)$ | Sıralı Dosya Taraması |
| **Tam Metin Arama (`search_table`)** | `.src` Ters İndeksli | Sıralı Dosya Taraması (Türkçe Normalizasyonlu) |
| **ACID İÅlemler (`transact_*`)** | Desteklenir (İndeks Geri Alma Dahil) | **Desteklenir (Ham Veri Geri Alma)** |
| **Sürekli Yedekleme AkıÅı (`recs_back`)** | Desteklenir (`backup/YYYY/`) | **Desteklenir (Aynı Dizinde `YYYY-MM-DD.csv`)** |
| **İkincil İndeksler (`.inx, .fld, .src, .fac`)** | OluÅturulur ve Güncellenir | **OluÅturulmaz (Sıfır İndeks Maliyeti)** |
| **URL Slug Rewrite (`.slg`)** | Otomatik Ãretilir | Devre DıÅı |
| **Denetim İzi (`.aut`) ve ArÅiv (`.del`)** | Åema Kuralına Göre Tutulur | Devre DıÅı |
| **Dizin Yapısı** | `tables/`, `schema/`, `backup/` vb. | **Düz Kök Dizin (`$dbase_dir/<tablo>.db`)** |
| **İkincil İndeksler (`.inx, .fld, .src, .fac`)** | OluÅturulur ve Güncellenir | **OluÅturulmaz (Sıfır İndeks Maliyeti)** |
| **URL Slug Rewrite (`.slg`)** | Otomatik Ãretilir | Devre DıÅı |
| **Denetim İzi (`.aut`) ve ArÅiv (`.del`)** | Åema Kuralına Göre Tutulur | Devre DıÅı |
| **Dizin Yapısı** | `tables/`, `schema/`, `backup/` vb. | **Düz Kök Dizin (`$dbase_dir/<tablo>.db`)** |
---
## 6. İndeksleme ve Arama Mekanizması
AmberDB, tablolara hızlı eriÅim saÄlamak için veriyi Åemada tanımlanan kurallara göre ikili (binary) indeks dosyalarına yazar.
### 6.1 İndeks Türleri
| Dosya Uzantısı | İndeks Türü | Açıklama |
|---|---|---|
| `.inx` | Kayıt İndeksi | Tablodaki tüm aktif ID'lerin sıralı ikili dizisi, toplam kayıt ve son ID bilgisi. |
| `.fld` | EÅleÅtirme (Match) | Blok bazlı deÄer eÅleÅtirmesi (`field_fetch`). DeÄer â ID ikili dizisi. |
| `.unq` | Tekillik & Alan SözlüÄü | `.fld` eÅlikçisi ve tekillik denetimi; serbest metinleri sayısal ID'lere baÄlayan çift yönlü sözlük (`.unq`). |
| `.src` | Tam Metin (Search) | Kelime bazlı ters indeks (`search_table`). Kelime â ID ikili dizisi. |
| `.inx` | Sıralama (Sort) | Belirlenen bloklara göre önceden sıralanmıŠikili RID dizisi (`sort_block`). |
| `.fac` | Facet İndeksi | E-ticaret filtreleme panelleri için kayıt baÅına aktiflik ve özellik haritası. |
| `.slg` | Slug Haritası | `_0.slg` (ID â Slug) ve `_1.slg` (Slug â ID) çift yönlü URL eÅleÅtiricisi. |
### 6.2 8-Bayt İkili (Binary) Paketleme Standardı
AmberDB, indeks dosyalarında maksimum performans ve minimum disk boyutu elde etmek için **8-baytlık homojen ikili paketleme** kullanır:
- **Sayısal ID'ler:** İkili indeksler (`.inx`, `.src`, `.fld`) kayıt kimliklerini saf 64-bit Big-Endian iÅaretsiz tam sayı (`(Q>)*`) olarak 8 baytlık sabit geniÅlikli bloklar halinde paketler.
- **Metin Anahtarlar (`use_simple => 1`):** UUID, e-posta, slug veya serbest metin anahtarlar gerektiÄinde ilgili tablo `use_simple => 1` bayraÄı ile yapılandırılır. Bu modda ikili indeks (`.inx`) yükü ortadan kalkar ve 255 bayta kadar serbe...
Bu sayede milyonlarca kayıt içeren indeks dosyalarında sayfalama (`LIMIT/OFFSET`), belleÄe tüm listeyi yüklemeden doÄrudan `substr` ile $O(1)$ zero-copy ikili ofset dilimleme yöntemiyle gerçekleÅtirilir.
### 6.3 EÅleÅtirme İndeksi (`.fld`) ve Ãift Yönlü Alan SözlüÄü (`.unq`)
AmberDB'de `match_block` içinde tanımlanan alanlar için indeksleme iki tamamlayıcı katmanda gerçekleÅir:
1. **İkili EÅleÅtirme İndeksi (`.fld`):**
AmberDB'de her blok için ayrı dosya açılmaz; tüm alan eÅleÅmeleri tek bir `<tablo>.fld` dosyasında toplanır. Bu dosya, `"$blok:$deger"` anahtarları karÅılıÄında ilgili kayıt ID'lerini 8-baytlık ikili paketlenmiÅ diziler (`(Q>)*`)...
2. **Ãift Yönlü Alan SözlüÄü (`.unq`):**
EÄer indekslenen alan serbest metin (kategori adı, marka adı, yazar, etiket vb.) içeriyorsa, motor otomatik olarak `<tablo>_<blok>.unq` sözlük dosyasını yönetir:
* **İleri Yön (`s:<metin>` $\rightarrow$ `$nid`):** Metin ifadelerine benzersiz artan sayısal bir kimlik (`$nid`) atar.
* **Geri Yön (`n:$nid` $\rightarrow$ `<metin>`):** Sayısal kimlikten orijinal metin etiketine anında dönüŠsaÄlar.
* **Otomatik Ãözümleme:** `field_fetch` veya `field_filter` çaÄrıldıÄında geliÅtirici ister sayısal ID (`12`) ister metin dizesi (`"Sony"`) versin, motor `.unq` sözlüÄünden deÄeri otomatik çözümler ve `.fld` üzerinden anında e...
### 6.4 Sıralama Mekanizması ve Kullanım Rehberi
AmberDB, tablolardaki belirli bloklara göre yüksek performanslı ve önceden indekslenmiÅ sıralama yeteneÄi sunar.
#### 6.4.1 Åema Yapılandırması (`sort_block`)
Sıralama yapılacak alanlar tablo Åema dosyasında (`.table`) tanımlanır. Sadece blok numarası verilebileceÄi gibi (`4`), sayısal veya tarihsel alanlar için tip (`type`) belirtilebilir:
```perl
# dbstore/schema/catalog_product.table
{
sort_block => [
4, # Blok 4: BaÅlık (Metin sıralaması)
{ blk => 10, type => 'num' }, # Blok 10: Fiyat (Sayısal sıralama)
{ blk => 12, type => 'date' }, # Blok 12: Tarih sıralaması (YYYYMMDDHHMMSS)
],
}
```
#### 6.4.2 Sorgularda Sıralama Kullanımı
`read_all`, `field_fetch` ve `search_table` fonksiyonlarında `sort` parametresi kullanılarak sorgular anında sıralı Åekilde alınır:
docs/TR.AmberDB_Veritabani_Sistemi.md view on Meta::CPAN
my @yeni_urunler = (
[ 0, "5", "3", "Kablosuz Kulaklık", "149.90", "2026-08-28", "1" ],
[ 0, "5,12", "8", "Mekanik Klavye", "299.00", "2026-08-28", "1" ],
[ 0, "12", "3", "Oyuncu Faresi", "89.50", "2026-08-28", "1" ],
# ... yüzlerce kayıt ...
);
my $statu = $adb->insert_list("catalog_product", @yeni_urunler);
# $statu hashref döner: { 101 => 1, 102 => 1, 103 => 1, ... }
```
### 8.3 Toplu Kayıt Güncelleme (`update_list`)
```perl
my @guncellemeler = (
[ 101, "5", "3", "Kablosuz Kulaklık Pro", "179.90", "2026-08-28", "1" ],
[ 102, "5,12", "8", "Mekanik Klavye RGB", "329.00", "2026-08-28", "1" ],
);
my $statu = $adb->update_list("catalog_product", @guncellemeler);
```
### 8.4 Toplu Kayıt Silme (`delete_list`)
```perl
# Silinecek ID'ler doÄrudan liste veya dizi referansı olarak verilebilir
my $statu = $adb->delete_list("catalog_product", 101, 102, 103);
# veya:
# $adb->delete_list("catalog_product", [101, 102, 103]);
```
### 8.5 Büyük Veri Yüklemelerinde (ETL) Chunk (Dilimleme) Stratejisi
Ãok büyük veri setlerinde (örn. 50.000+ kayıt), RAM tüketimini optimize etmek ve disk buffer'ını rahatlatmak için verileri 500-1000'lik parçalara bölerek aktarmak en iyi pratiktir:
```perl
my $chunk_size = 1000;
for (my $i = 0; $i < @buyuk_veri; $i += $chunk_size) {
my $end = $i + $chunk_size - 1;
$end = $#buyuk_veri if $end > $#buyuk_veri;
my @chunk = @buyuk_veri[$i .. $end];
$adb->insert_list("catalog_product", @chunk);
}
```
---
## 9. Åema Yapılandırması (.table ve Kod İçi / In-Memory)
AmberDB Åema güdümlü (schema-driven) bir veritabanı motorudur. Tablo Åemaları; birincil anahtar kısıtlamalarını, alan tiplerini, çok boyutlu indeksleri, otomatik slug kaydı üretimini, facet filtrelerini, yaÅam döngüsü (junk) kuralla...
### 9.1 Veritabanı ve Tablo Dizin Yapısı
AmberDB tabloları, Åemaları ve geçici/kalıcı dosyaları, belirlenen `dbstore` ana veri dizini altında fiziksel klasörlere ayrılarak saklanır:
| Dizin | Görevi |
|---|---|
| `dbstore/table/` | Kalıcı `.db` ana veri, `.inx` kayıt ve sıralama indeksi, `.fld` eÅleÅtirme, `.src` arama, `.fac` facet, `.slg` slug dosyaları |
| `dbstore/schema/` | Kalıcı `.table` tablo Åemaları ve `.dbase` grup yapılandırma dosyaları |
| `dbstore/config/` | Kalıcı `.conf` düz metin ayar ve konfigürasyon dosyaları, `connect.pl` profil dosyası |
| `dbstore/backup/` | Günlük CSV denetim yedekleri (`dbgun/YYYYMMDD/`) |
| `dbstore/journal/`| İÅlem geri alma (WAL) ve Tier 4 gecikmeli yazma günlükleri (`txn_*`, `sync_ramdisk`) |
| `dbstore/lock/` | RAM-disk baÄlı deÄilken süreç ve tablo seviyesi kilit dosyaları (`*.lock`) |
| `dbstore/session/`| RAM-disk baÄlı deÄilken süreç oturum dosyaları (`*.sess`) |
> [!NOTE]
> **RAM-Disk Dizin Yapısı:** İÅletim sisteminde RAM-disk baÄlandıÄında (Windows'ta `R:/amberdb_$dbname`, Linux'ta `/dev/shm/amberdb_$dbname`, macOS'ta `/Volumes/amberdb_$dbname`), RAM-disk kök dizini altında dinamik olarak `table/`, `schema...
> [!IMPORTANT]
> **Dizin Yapısı Uyumluluk Notu:** Eski projelerden yükseltme yaparken yapmanız gereken tek fiziksel iÅlem; veritabanı dizininizdeki `dbstore/scheme/` klasörünün adını **`dbstore/schema/`** olarak yeniden adlandırmaktır. Kod ve API taraf...
### 9.2 Åemanın Rolü ve EsnekliÄi: Zorunlu mu, İsteÄe BaÄlı mı?
AmberDB'de Åema tasarımı **tamamen esnek ve katmanlıdır**:
* **Minimalist / Hafif Kullanım:** Åema dosyasında `blocks` (alan listesi) tanımlamak **zorunlu deÄildir**. Sadece hangi blokların indeksleneceÄini belirten `record_index`, `match_block`, `search_block` ve `sort_block` tanımlanarak ultra hafi...
```perl
# dbstore/schema/catalog_product.table
{
name => "Ãrün KataloÄu",
record_index => 1, # .inx birincil indeksini ve auto-increment sayacını açar
match_block => [ 1, 2, 3, 11 ], # .fld Birebir eÅleÅme (Kategori, Marka, Yazar, Statü)
search_block => [ 4, 5, 7, 9 ], # .src Tam metin arama (Ad, Alt BaÅlık, Açıklama, Barkod)
sort_block => [ 4, { blk => 10, type => 'num' } ], # .inx Ãnceden sıralanmıŠbinary ID indeksleri
keep_deleted => 1, # Silinenleri .del dosyasında sakla (Soft-delete)
log_owner => 1, # DeÄiÅiklikleri yapan kullanıcıyı .aut dosyasına yaz
}
```
* **GeliÅmiÅ / Form ve DoÄrulama Destekli Kullanım:** `blocks` dizisi tanımlandıÄında; alan veri tipleri (`type`), form arayüz giriÅ bileÅenleri (`input`), zorunlu/geçerli alan doÄrulamaları (`valid`) ve iliÅkili tablo eÅleÅmeleri (`...
### 9.3 Åema Tanımlama ve Okuma Yöntemleri (`table_info` & `table_attr`)
AmberDB'de Åema iki Åekilde tanımlanabilir ve programatik olarak okunabilir:
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.
### 9.4 Å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:
docs/TR.AmberDB_Veritabani_Sistemi.md view on Meta::CPAN
$adb->update_id("catalog_product", 101, @guncel_veri);
```
### 13.6 RAM-Disk Yönetimi ve Yardımcı Araçlar
AmberDB, iÅletim sistemine özgü RAM-disk baÄlama noktalarını yerleÅik olarak destekler:
- **Windows:** `bin\setup_windows.bat start 512M R:` ile ImDisk sanal sürücüsü oluÅturulur. Durum denetimi `bin\setup_windows.bat status`, baÄlantı sonlandırma ise `bin\setup_windows.bat stop R:` ile yapılır.
- **Linux:** `/dev/shm` dizini otomatik olarak paylaÅımlı bellek alanı olarak tanınır.
- **macOS:** `/Volumes` altındaki APFS RAM-disk birimleri otomatik olarak kullanılır.
- **Arka Plan EÅitleme Daemon'ı (Tier 4):** `perl bin/amberdb_daemon.pl start` komutuyla baÅlatılır, `status` ile izlenir ve `stop` ile güvenle durdurulur.
- **Depolama Düzeni Senkronizasyonu:** `amberdb update storage` veya `perl bin/amberdb_cli.pl update storage --force` ile tüm dizinler güncellenir.
### 13.7 Uçucu Tablolar ve Kayan TTL Zaman AÅımı (`ramdisk_ttl`)
`ramdisk_ttl` parametresi **yalnızca `use_ramdisk => 3` (uçucu RAM-disk)** modunda çalıÅan tablolar için geçerlidir (varsayılan: 300 saniye). Süresi dolan kayıtlar eriÅim anında otomatik olarak temizlenir:
```perl
# Session tablosunu uçucu RAM-disk ve 30 dakika TTL ile ayarlama
$adb->table_attr("session", {
use_ramdisk => 3,
ramdisk_ttl => 1800, # 30 dakika kayan TTL (yalnızca Tier 3 için geçerli)
table_dir => 'session' # ramdisk/session/ altında saklar
});
```
### 13.8 Ãzel Tablo Dizini (`table_dir`)
Tablolar varsayılan olarak `tables/` dizininde saklanır. `table_dir` parametresi ile istenilen alt klasöre yönlendirilebilir:
```perl
# SipariÅ tablosunu 'siparis' dizinine yerleÅtirme:
# Fiziksel: dbstore/siparis/siparis_tablosu.db
# RAM-Disk: ramdisk/siparis/siparis_tablosu.db
$adb->table_attr("siparis_tablosu", table_dir => 'siparis');
# Kök dizine yerleÅtirme (tables/ önekini ezme):
$adb->table_attr("kok_tablosu", table_dir => '');
```
### 13.9 Disk Tabanlı Geçici Buffer
Büyük veri aktarımlarında veya raporlama iÅlemlerinde RAM dıÅı geçici disk buffer'ı kullanılır:
```perl
$adb->buffer_write("rapor_gecici", @buyuk_veri);
my @veri = $adb->buffer_read("rapor_gecici");
$adb->buffer_delete("rapor_gecici");
```
---
## 14. Yapılandırma ve Deterministik Bayrak Yönetimi (`config`)
AmberDB'nin çalıÅma modunu deÄiÅtirmek ve yapılandırma bayraklarını güvenli bir Åekilde yönetmek için `$adb->config()` metodu kullanılır:
```perl
# Toplu veya tekli yapılandırma ataması (Ãnerilen)
$adb->config(
no_write => 1, # Bakım modu: Tüm yazma iÅlemlerini engelle
no_backup => 1, # Tüm tablolar için günlük CSV denetim yedeklerini kapat
use_simple => 1, # İndekssiz doÄrudan yazım modu (İkincil indeksler devre dıÅı bırakılır)
keys_only => 1, # read_all çaÄrılarında sadece ID'leri döndür
ramdisk_size => '1024M', # RAM-Disk (tmpfs/APFS/ImDisk) boyutu (Varsayılan: 512M)
);
# Tekil okuma:
my $no_write = $adb->config('no_write');
# Toplu okuma (Güvenli kopya döner):
my $cfg = $adb->config();
```
---
## 15. Veri Yapıları, DüÅük Seviyeli Tablo ve AkıŠİÅlemleri
AmberDB, standart CRUD katmanının altında doÄrudan `DB_File` C seviyesi optimizasyonlarına ve ham akıŠiÅlemlerine eriÅim sunar:
### 15.1 Veri Yapıları ve Serialization (`db_encode`, `db_decode`)
AmberDB, karmaÅık Perl yapılarını özel ayıraçlarla yüksek hızda dizgeleÅtirir (serialize eder):
```perl
# Encode: Perl Verisi â String
my $str = $adb->db_encode("Metin", [ 1, 2, 3 ], { key => "val" });
# Decode: String â Perl Verisi
my ($metin, $dizi_ref, $hash_ref) = $adb->db_decode($str);
```
### 15.2 DüÅük Seviyeli Tablo ve AkıŠYönetimi (`table_read`, `table_write`, `table_close`)
Büyük veri aktarımlarında veya özel toplu iÅlerde dosya oturumu açıp kapatmak için kullanılır:
```perl
my $tablo_yolu = $adb->table_path("catalog_product") . ".db";
# 1. Yazma/Okuma Modunda Tablo Açma ve Kilit Uygulama (flock LOCK_EX)
my $db_obj = $adb->table_write($tablo_yolu);
# 2. Salt-Okunur Modda Tablo Açma (O_RDONLY)
my $db_ro = $adb->table_read($tablo_yolu);
# 3. Tabloyu Senkronize Etme (sync), Kilidi Ãözme ve Kapatma
$adb->table_close($tablo_yolu);
```
### 15.3 Ham Kayıt İÅleme Metodları (`recs_get`, `recs_put`, `recs_del`, `recs_exist`, `recs_keys`, `recs_scan`, `table_readid`)
Açık veya otomatik açılan dosya oturumu üzerinde doÄrudan `$db->get()`, `$db->put()`, `$db->del()` çaÄrıları yaparak maksimum performans saÄlar:
```perl
# 1. Ham DeÄerleri Toplu Okuma (recs_get)
my $ham_veriler = $adb->recs_get($tablo_yolu, 5001, 5002);
# $ham_veriler döner: { 5001 => "ham_veri_stringi", 5002 => "..." }
# 2. Otomatik Dosya Oturumu ile Tek Kayıt Okuma (table_readid)
my ($rid, @kayit) = $adb->table_readid($tablo_yolu, 5001);
# 3. Ham Kayıtları Toplu Yazma (recs_put)
docs/TR.AmberDB_Veritabani_Sistemi.md view on Meta::CPAN
\%secilen_filtreler,
$table_info->{facet_block},
{ limit => 10, sort => "count" } # En çok ürünü olan ilk 10 filtreyi göster
);
# $menu çıktısı doÄrudan Åablona gönderilmeye hazırdır:
{
count => 42, # Filtrelere uyan toplam ürün sayısı
ids => [ 101, 105, 120, ... ], # Ekranda listelenecek ürünlerin ID'leri
active_counts => { 1 => 1, 2 => 2 }, # Blok bazında aktif filtre sayısı
groups => [ # HTML sol menüsü için hazır gruplar:
{
blk => 2,
name => "Marka",
active => "1",
active_count => 2,
records => [
{ uid => "fc_2_12", param => "f2", val => 12, label => "İthaki", count => 28, checked => "1" },
{ uid => "fc_2_14", param => "f2", val => 14, label => "Can", count => 14, checked => "1" },
{ uid => "fc_2_19", param => "f2", val => 19, label => "YKY", count => 6, checked => "" },
]
},
...
]
}
```
#### B. Arama Sonuçları Sayfasında Dinamik Filtre Ãretme
Arama yapıldıÄında, bulunan ürünlerin ID listesini `base_ids` olarak vererek filtrenin sadece arama sonuçlarını kapsamasını saÄlarsınız:
```perl
# 1. Ziyaretçinin arama terimiyle ürünleri bul (keys_only ile limitsiz ID listesi)
my @bulunan_idler = $adb->search_table("catalog_product", "bilim kurgu", { keys_only => 1 });
# 2. Sadece bulunan bu ürünler arasından filtre menüsü üret
my $arama_menusu = $adb->facet_menu(
"catalog_attributes",
\%secilen_filtreler,
$table_info->{facet_block},
{ base_ids => \@bulunan_idler }
);
```
---
## 17. Kullanıcı Denetim İzi (Audit) ve Yedekleme
### 17.1 Kullanıcı İÅlem GeçmiÅi (`log_owner`)
Åemada `log_owner => 1` aktif olduÄunda, kaydın tüm geçmiÅi `.aut` dosyasında tutulur:
```perl
# Bir kaydın kimler tarafından ne zaman deÄiÅtirildiÄini HTML olarak alma
my $gecmis_html = $adb->auth_view("catalog_product", 5001);
print $gecmis_html;
# Ãıktı:
# add 2026-08-14 10:15 admin_maruf
# edit 2026-08-14 11:30 editor_ali
```
### 17.2 Sürekli DeÄiÅiklik AkıÅı (Continuous Recovery Stream - `YYYY-MM-DD.csv`)
AmberDB yapılan her `insert`, `modify` ve `delete` iÅlemini kronolojik zaman-serisi olarak `backup/YYYY/YYYY-MM-DD.csv` dosyasına otomatik olarak ekler (append-only).
Her satır tab ayrılmıŠ(`\t`) olarak Åu sütun yapısında yazılır:
`[Zaman Damgası] \t [Kullanıcı] \t [İÅlem] \t [Tablo] \t [Kayıt ID] \t [PaketlenmiÅ DeÄerler]`
Bu akıÅı devre dıÅı bırakmak için:
* **Tablo Åemasında (Tablo Bazlı):** Åema dosyasına `no_backup => 1` eklenirse sadece o tablo için yedekleme kapatılır.
* **Genel Düzeyde (Tüm Tablolar):** `$adb->config(no_backup => 1);` tanımlanırsa tüm tablolar için yedekleme kapatılır.
### 17.3 Native Veritabanı ArÅivi (`.amberdb` Dump & Restore)
AmberDB, tüm Åemaları (`schema/*.table`, `schema/*.dbase`) ve otoriter veri dosyalarını (`tables/*.db`, `tables/*.del`, `tables/*.aut`, `tables/*.cnt`) SHA-256 doÄrulama özetleriyle birlikte fiziksel dizin yapısıyla birebir örtüÅen sıkı...
TüretilmiÅ indeks dosyaları (`.inx`, `.src`, `.fld`, `.fac`, `.slg`) boyuttan tasarruf etmek için arÅiv içine konmaz; `restore` esnasında Åema kurallarına göre `set_index` ile deterministik olarak sıfırdan üretilir.
```perl
use AmberDB;
use AmberDB::Tools;
my $adb = AmberDB->new(path => { dbase_dir => "./dbstore" });
my $tools = AmberDB::Tools->new($adb);
# 1. Tüm veritabanının tam yedeÄini alma (.amberdb)
my $arsiv = $tools->dump();
# Ãıktı: dbstore/backup/2026/amberdb_2026-08-28_180000.amberdb
# 2. Belirli tabloların snapshot yedeÄini alma
$tools->dump(
file => "backup/2026/katalog_yedek.amberdb",
tables => ["catalog_product", "catalog_category"]
);
# 3. YedeÄi geri yükleme ve tüm indeksleri otomatik inÅa etme
$tools->restore(
file => "backup/2026/katalog_yedek.amberdb",
force => 1, # Var olan tabloların üzerine yazma izni
reindex => 1 # İndeksleri sıfırdan üret
);
```
#### CLI Komut Satırı Aracı (`bin/amberdb_backup.pl`)
```bash
# Veritabanını yedekleme
perl bin/amberdb_backup.pl --dump --file backup/2026/tam_yedek.amberdb
# Belirli tabloları yedekleme
perl bin/amberdb_backup.pl --dump --tables products,orders
# YedeÄi güvenli Åekilde geri yükleme
perl bin/amberdb_backup.pl --restore --file backup/2026/tam_yedek.amberdb --force
```
---
## 18. Bakım ve Onarım Araçları (AmberDB::Tools)
Veritabanı indekslerini sıfırdan yeniden oluÅturmak, veri doÄrulaması yapmak veya tabloları optimize etmek için `AmberDB::Tools` kullanılır:
```perl
use AmberDB;
use AmberDB::Tools;
my $adb = AmberDB->new(path => { dbase_dir => "./dbstore" });
my $tools = AmberDB::Tools->new($adb);
# 1. Bir tablonun tüm indekslerini sıfırdan oluÅturma (Re-Index)
$tools->set_index("catalog_product");
# 2. Tüm veritabanındaki bütün tabloları yeniden indeksleme
$tools->index_alltables();
# 3. İndeks Tutarlılık Kontrolü
my @kayitlar = $adb->read_all("catalog_product", { no_index => 1 });
my $fark = $tools->check_readall("catalog_product", @kayitlar);
# 4. Tablo Vakumlama (Fragmentasyonu temizler ve dosyayı küçültür)
$tools->vacuum("catalog_product", 1); # 1 = iÅlem sonrası reindex yap
# 5. DB_File tablosunu CSV'ye aktarma veya CSV'den geri yükleme
$tools->tie2csv("catalog_product");
$tools->csv2tie("catalog_product");
# 6. Tüm Veritabanı Tablolarını Toplu Yeniden İndeksleme / DönüÅtürme
my $donusum_raporu = $tools->convert_tables();
# 7. Tabloyu ve İliÅkili Tüm İkincil İndeks Dosyalarını Diskten Silme
$tools->del_table("eski_tablo");
# 8. BaÄımsız / Geçici Dizinler için Hafif Ad-Hoc AmberDB ÃrneÄi
my $basit_adb = $tools->db_simple("/path/to/data/dir");
```
---
## 19. Dosya Uzantıları Haritası
AmberDB dosya uzantıları rollerine ve yeniden üretilebilirlik durumlarına göre 3 grupta toplanır:
| Uzantı | Rol / Sınıf | Yeniden Ãretilebilir mi? | Açıklama |
|---|---|---|---|
| **Temel & Otoriter Veriler** | | | |
| `.db` | Birincil Veri (Source of Truth) | **Hayır** (Otoriter) | Berkeley DB ana döküman tablosu (`DB_File` Hash). |
| `.del` | Silinen Kayıtlar ArÅivi | **Hayır** (Otoriter) | Silinen (soft-delete) kayıtların arÅivi (`keep_deleted`). |
| `.aut` | Kullanıcı Denetim İzi (Audit) | **Hayır** (Otoriter) | Kimin ne zaman hangi kaydı deÄiÅtirdiÄinin logu (`log_owner`). |
| `.unq` | Tekillik & Metin SözlüÄü | **Hayır** (Otoriter) | Benzersizlik kısıtları ve serbest metinleri sayısal foreign key ID'lerine baÄlayan çift yönlü sözlük. |
| **TüretilmiŠİndeks Dosyaları** | | | |
| `.inx` | Birincil Kayıt İndeksi | **Evet** (`set_index`) | Tüm aktif ID listesi, kayıt sayısı ve son ID ikili indeksi. |
| `.fld` | EÅleÅtirme İndeksi (Match) | **Evet** (`set_index`) | Alan bazlı tersine eÅleÅtirme indeksi (`match_block`). |
| `.src` | Tam Metin Arama (Search) | **Evet** (`set_index`) | Kelime bazlı tersine arama indeksi (`search_block`). |
| `.inx` | Sıralama İndeksi (Sort) | **Evet** (`set_index`) | Belirlenen bloklara göre sıralı ID ikili indeksi (`sort_block`). |
| `.fac` | Facet Filtreleme İndeksi | **Evet** (`set_index`) | E-ticaret filtre sayaç ve durum haritası (`facet_block`). |
| `.slg` | Slug Haritası | **Evet** (`set_index`) | `_0.slg` (IDâSlug) ve `_1.slg` (SlugâID) çift yönlü eÅleÅtirici. |
| **ÃalıÅma Zamanı ve Geçici Dosyalar** | | | |
| `.cnt` | Sayaç Dosyası | Sayaç verisi | Kayıt görüntülenme/tıklanma sayaçları (`use_counter`). |
| `.tmp` | Disk Buffer Dosyası | Geçici (Staging) | `dbstore/buffer/` altında geçici aktarım/ETL dosyası (`buffer_write`). |
| `.lock` | Süreç Kilit Dosyası | Geçici (Mutex) | İÅletim sistemi `flock` process senkronizasyon dosyası. |
---
## 20. Dizin Yapısı
```text
dbstore/
âââ schema/ â Åema ve Grup Tanımları
â âââ catalog.dbase â Grup tanımı
â âââ catalog_product.table â Ãrün tablosu Åeması
â âââ catalog_category.table â Kategori tablosu Åeması
âââ tables/ â Ana Veri ve İndeks Dosyaları
â âââ catalog_product.db â Ana veri
â âââ catalog_product.inx â İkili kayıt ve sıralama indeksi
â âââ catalog_product.fld â Birebir eÅleÅtirme indeksi (tüm bloklar "$blk:$val")
â âââ catalog_product.src â Tam metin arama indeksi
â âââ catalog_product.fac â Facet filtreleme indeksi
â âââ catalog_product.unq â Alan metin sözlüÄü
â âââ catalog_product.slg â Ãift yönlü URL slug haritası ("0:$id", "1:$slug")
â âââ catalog_product.aut â Denetim logu
â âââ catalog_product.del â Silinen kayıtlar
âââ ramdisk/ â RAM-Disk PaylaÅımlı Bellek ve Hızlı Depolama (Linux tmpfs, macOS APFS, Windows ImDisk)
âââ buffer/ â Geçici Disk Buffer / Staging Dosyaları
âââ journal/ â Aktif Transaction Günlükleri (txn_*)
âââ pids/ â Dosya ve Kayıt Kilitleri
âââ backup/ â Günlük CSV Yedekleri
```
---
## 21. GeliÅtirici Tavsiyeleri ve En İyi Pratikler
1. **Toplu Veri GiriÅinde `insert_list` Kullanın:** Yüzlerce kaydı tek tek döngüde `insert_id` ile eklemek yerine tek seferde `insert_list` ile ekleyin; disk I/O ve indeksleme süresi 10 kat hızlanacaktır.
2. **Kritik İŠMantıklarında `transact_start` Kullanın:** Stok düÅme, bakiye güncelleme ve sipariÅ onaylama gibi adımları mutlaka transaction bloÄu içine alın.
3. **Åemalarda Gereksiz Blokları İndekslemeyin:** Yalnızca filtrelenecek alanları `match_block`, aranacak alanları `search_block` olarak tanımlayın.
4. **Sayfalama Dönen DeÄer İmzasını DoÄru KarÅılayın:** `read_all`, `field_fetch` ve `search_table` metotlarında `$limit > 0` verildiÄinde dönen listenin ilk elemanının `$toplam` tamsayısı olduÄunu unutmayın. Asla `my @kayitlar = $a...
5. **Kayıt ID Tipi ve Basit Mod Seçimi:** Standart iliÅkisel tablolar 64-bit tam sayı ID'ler ile çalıÅarak ikili sabit boyutlu ofsetler (`(Q>)*`) üzerinde en yüksek dilimleme hızını sunar. UUID, slug veya oturum belirteçleri gibi serbest...
6. **Kayıt Dizisinde ID Standartı:** Kayıt dizilerinde (`@record`) her zaman 0. indisi Kayıt ID'si (`$record[0]`) olarak konumlandırın. Yeni kayıtta `0` verip `my $id = $record[0] = $adb->insert_id("tablo", @record);` Åeklinde atayın. Okuma ...
---
## 22. Kapsamlı Uygulama ÃrneÄi (SipariÅ & Stok Senaryosu)
AÅaÄıdaki örnek; ana tabloların oluÅturulması, ürünün iliÅkisel ID'ler ve çoklu kategorilerle eklenmesi, URL slug ile okuma, filtreli arama, sıralama ve güvenli bir sipariÅ transaction'ını baÅtan sona gösterir:
```perl
use strict;
use warnings;
use AmberDB;
# 1. Motoru baÅlat
my $adb = AmberDB->new(
cfg => { language => "tr", user => "kasiyer_1" },
path => { dbase_dir => "./dbstore" }
);
# 2. Ana Tanım Tablolarına Kayıt Ekleme (Master Tables)
my $kat_bilgisayar = $adb->insert_id("catalog_category", undef, "Bilgisayar & BiliÅim", 1); # ID: 5
my $kat_tasinabilir = $adb->insert_id("catalog_category", undef, "TaÅınabilir Cihazlar", 1);# ID: 12
my $marka_apple = $adb->insert_id("catalog_brand", undef, "Apple", "ABD"); # ID: 8
my $yazar_tasarim = $adb->insert_id("catalog_author", undef, "Donanım Ekibi", "Ar-Ge"); # ID: 7
# 3. Yeni Ãrün Ekle (İliÅkisel alanlara ID verilir; kategori "5,12" olarak çoklu tutulur)
my @urun = (
"5,12", # [1] Kategori ID'leri (5: Bilgisayar, 12: TaÅınabilir)
"8", # [2] Marka ID: Apple (8)
"7", # [3] Yazar / Katkıda Bulunan ID: 7
"MacBook Pro M3", # [4] Ãrün Adı
"16GB RAM 512GB SSD Uzay Grisi",# [5] Açıklama
"", "", "",
10, # [8] Stok: 10 adet
"195949123456", # [9] Barkod
"64999.00", # [10] Fiyat
"1" # [11] SatıÅta: 1
);
my $urun_id = $adb->insert_id("catalog_product", undef, @urun);
print "1. Ãrün Eklendi -> ID: $urun_id\n";
# 4. Otomatik Ãretilen URL Slug'ı Oku
my $slug_harita = $adb->get_slug("catalog_product", 0, $urun_id);
print "2. OluÅan URL -> /urun/$slug_harita->{$urun_id}\n";
# 5. Ãoklu Kategoriden (Ãrn: 12 nolu TaÅınabilir) Fiyat Sıralı Listeleme, ilk 20 kayıt
my ($toplam, @urunler) = $adb->field_fetch(
( run in 2.643 seconds using v1.01-cache-2.11-cpan-99fa8243a42 )