Node.js'ten PostgreSQL'e bağlanmak

Ders 27 ve 28'de yazdığın API'lerin verisi bir dizide, Ders 29'da bir JSON dosyasında duruyordu. Ders 33–36'da ise veriyi PostgreSQL tablolarına koydun ve Neon'un SQL Editor'ünde sorguladın. Bu iki dünya şimdiye kadar birbirini hiç görmedi.

Bu derste onları birleştiriyorsun: Node.js'ten veritabanına bağlanacak, her istekte SQL çalıştırıp satırları JSON olarak döndürecek, kullanıcının yazdığı değerleri sorguya güvenle koyacak ve veritabanının hatalarını anlamlı HTTP yanıtlarına çevireceksin. Sonunda tablolarını sıralı dosyalarla değiştirmeyi öğrenecek ve ORM denen araçları tanıyacaksın. Takım API'ni Postgres'e taşımak Ders 38'in projesi; bu derste aynı mekanizmayı küçük ve temiz bir API üzerinde, parça parça kuruyorsun.

#Üç program, tek istek

Bir isteğe artık üç program katılıyor. İstemci (tarayıcı ya da curl.exe) Express'e bir HTTP isteği atar. Express isteğe bakar, hangi SQL'in çalışacağına karar verir ve sorguyu veritabanına gönderir. PostgreSQL satırları geri yollar; Express onları JSON'a çevirip istemciye döndürür.

İstemci veritabanını hiç görmez. Veritabanının adresi ve şifresi yalnız sunucunda durur; dışarıya açık tek kapı senin API'n. Kimin neyi okuyup yazabileceğine de böylece sen karar verirsin.

Express ile PostgreSQL arasındaki konuşmayı pg paketi yapar. Postgres HTTP konuşmaz; kendi protokolünü, açık tutulan bir bağlantı üzerinden konuşur. pg bu dili bilen bir veritabanı sürücüsüdür: sen pool.query("SELECT ...") yazarsın, o sorguyu Postgres'in anlayacağı mesajlara çevirip gönderir, gelen yanıtı JavaScript objelerine dönüştürür.

#Proje klasörü ve pg paketi

Bu derste yeni bir proje klasöründe çalışacaksın. Terminalde cd C:\kod ile kod klasörüne geç, mkdir pg-api ile klasörü oluştur ve cd pg-api ile içine gir. Sonra package.json oluştur ve iki paket kur: Express ve pg.

PS C:\kod\pg-api> npm init -yWrote to C:\kod\pg-api\package.json: {  "name": "pg-api",  "version": "1.0.0",  "description": "",  "main": "index.js",  "scripts": {    "test": "echo \"Error: no test specified\" && exit 1"  },  "keywords": [],  "author": "",  "license": "ISC",  "type": "commonjs"} PS C:\kod\pg-api> npm install express pg added 79 packages, and audited 80 packages in 2s 28 packages are looking for funding  run `npm fund` for details found 0 vulnerabilities

Klasörü VS Code'da aç (File → Open Folder). package.json'da "type" satırını "module" yap; böylece import yazabilir ve await'i dosyanın en üst düzeyinde kullanabilirsin (Ders 14, Ders 15). Sonra scripts kısmını iki betikle değiştir:

1{2  "name": "pg-api",3  "version": "1.0.0",4  "description": "",5  "main": "index.js",6  "scripts": {7    "dev": "node --watch --env-file=.env app.js",8    "start": "node --env-file=.env app.js"9  },10  "keywords": [],11  "author": "",12  "license": "ISC",13  "type": "module",14  "dependencies": {15    "express": "^5.3.0",16    "pg": "^8.23.1"17  }18}

• --env-file=.env: Node, programı başlatmadan önce .env dosyasındaki değişkenleri process.env'e yükler (Ders 29).
• --watch: dosyayı her kaydettiğinde programı yeniden başlatır (Ders 27).
• dev geliştirirken, start canlı ortamda kullanılır.

Bu ders Express 5.3.0 ve pg 8.23.1 ile denendi. Senin sürümlerin biraz daha yeni olabilir; npm view pg version en güncelini söyler.

Birazdan veritabanı şifren .env dosyasında duracak. O dosya Git'e asla girmemeli, bu yüzden işe .gitignore ile başla:

1node_modules2.env

#Veritabanını hazırla: schema.sql

Ders 36'daki tabloların Neon'da duruyor ve görevlerde onları değiştirmiş olabilirsin. Bu derste aynı oyuncular ve maclar tablolarının sade bir kopyasını, derse ayrılmış temiz bir veritabanında kuracaksın; böylece senin gördüğün sonuçlar dersteki çıktılarla birebir aynı olur. Bir Neon projesinde birden çok veritabanı yan yana durabilir.

1CREATE TABLE oyuncular (2    id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,3    ad text NOT NULL UNIQUE,4    bolge text NOT NULL5);6 7CREATE TABLE maclar (8    id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,9    oyuncu_id integer NOT NULL REFERENCES oyuncular (id),10    sampiyon text NOT NULL,11    sonuc text NOT NULL CHECK (sonuc IN ('zafer', 'yenilgi')),12    kill integer NOT NULL CHECK (kill >= 0),13    tarih timestamptz NOT NULL DEFAULT now()14);

Tablolar Ders 36'dakilerin kısaltılmış hâli; olum ve asist yok. İki küçük fark var: kill eksi olamaz (CHECK, Ders 35) ve tarih sütunu maçın kaydedildiği anı tutar. DEFAULT now() sayesinde tarihi sen yazmazsan Postgres o anı koyar.

1INSERT INTO oyuncular (ad, bolge) VALUES2    ('Deniz', 'TR'),3    ('Ece', 'TR'),4    ('Mert', 'EUW'),5    ('Selin', 'TR'),6    ('Kaan', 'EUW');7 8INSERT INTO maclar (oyuncu_id, sampiyon, sonuc, kill) VALUES9    (1, 'Ahri', 'zafer', 8),10    (1, 'Lux', 'yenilgi', 3),11    (2, 'Jinx', 'zafer', 12),12    (1, 'Ahri', 'zafer', 10),13    (3, 'Garen', 'yenilgi', 2),14    (2, 'Lux', 'zafer', 6),15    (4, 'Teemo', 'yenilgi', 4);

Kaan'ın hiç maçı yok; istatistik yazarken bu boşluk işine yarayacak. İki dosya artık projenin parçası. schema.sql veritabanının şemasını, yani iskeletini anlatıyor: bir gün yeni bir veritabanı kurman gerekirse (takım arkadaşının bilgisayarı, canlı ortam) aynı dosyayı çalıştırırsın. Tablolar sonradan değişince ne yapacağını dersin sonunda, göç bölümünde göreceksin.

#Bağlantı dizesi ve .env

Node'un Neon'a bağlanması için tek satırlık bir bilgi gerekiyor: bağlantı dizesi (connection string). Neon'da proje sayfasındaki Connect düğmesine bas ve açılan pencerede veritabanı olarak pgapi'yi seç. Şuna benzeyen bir dize görürsün (arayüz değişmiş olabilir; değerler Neon'un belgesindeki örnek):

postgresql://neondb_owner:AbC123dEf@ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech/pgapi?sslmode=require&channel_binding=require

Dizeyi koda yazmak yerine .env dosyasına koy (Ders 29). Proje klasöründe .env adında bir dosya aç ve tek satır yaz:

1DATABASE_URL=postgresql://neondb_owner:AbC123dEf@ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech/pgapi?sslmode=verify-full&channel_binding=require

Buraya kendi dizeni yapıştır. Tek bir değişiklik yap: sslmode=require'ı sslmode=verify-full yap. Nedenini hemen aşağıda anlatıyorum.

#sslmode: şifreli bağlantı

Bilgisayarınla Neon arasındaki yol internet; araya giren biri trafiği okuyabilir. SSL (bugünkü adıyla TLS) bağlantıyı şifreler ve karşıdaki sunucunun gerçekten Neon olduğunu sertifikasıyla kanıtlar. Tarayıcıdaki https'in (Ders 18) veritabanı tarafındaki karşılığı budur. Neon şifrelenmemiş bağlantıyı hiç kabul etmez.

sslmode bu işin ne kadar sıkı yapılacağını söyler: require "şifrele" der, verify-full ise ayrıca sunucunun sertifikasını ve adını da denetler. Neon her zaman verify-full kullanmanı öneriyor.

Neon'un verdiği dizede sslmode=require yazar. Onu değiştirmezsen pg 8.23, birazdan yazacağın her programın açılışında şu uzun uyarıyı basar:

PS C:\kod\pg-api> node --env-file=.env deneme.js(node:29044) Warning: SECURITY WARNING: The SSL modes 'prefer', 'require', and 'verify-ca' are treated as aliases for 'verify-full'.In the next major version (pg-connection-string v3.0.0 and pg v9.0.0), these modes will adopt standard libpq semantics, which have weaker security guarantees. To prepare for this change:- If you want the current behavior, explicitly use 'sslmode=verify-full'- If you want libpq compatibility now, use 'uselibpqcompat=true&sslmode=require' See https://www.postgresql.org/docs/current/libpq-ssl.html for libpq SSL mode definitions.(Use `node --trace-warnings ...` to show where the warning was created)...

Uyarı şunu söylüyor: pg şu an require'ı en sıkı mod olan verify-full gibi uyguluyor, ama 9. sürümde require daha gevşek davranacak. Bugünkü güvenli davranışı korumak için açıkça verify-full yaz.

Neon'un sertifikası herkesin tanıdığı Let's Encrypt kökünden geldiği için ek bir dosyaya gerek yok. Dizedeki channel_binding=require'ı ise pg kullanmaz; durması zarar vermez.

#İlk sorgu: Pool ve query

Veritabanıyla konuşan kodu tek bir dosyada topla. db.js adında bir dosya aç:

1import { Pool } from "pg"2 3export const pool = new Pool({4    connectionString: process.env.DATABASE_URL5})

• import { Pool } from "pg": pg paketinden Pool sınıfını al (Ders 14, Ders 16).
• new Pool({ ... }): bir bağlantı havuzu kur. Ne olduğunu birazdan göreceksin; şimdilik "veritabanına açılan kapı" diye düşün.
• connectionString: process.env.DATABASE_URL: kapının adresi .env'den gelir. Kodda şifre yok.
• export const pool: programın her dosyası bu havuzu içe aktarır. Node bir modülü yalnız ilk içe aktarılışında çalıştırır; db.js'i kaç dosya içe aktarırsa aktarsın havuz tektir.

Şimdi deneme.js adında bir dosya aç ve ilk sorgunu yaz:

1import { pool } from "./db.js"2 3const sonuc = await pool.query(4    "SELECT 'Merhaba Postgres' AS mesaj, 2 + 3 AS toplam"5)6console.log(sonuc.rows)7await pool.end()

PS C:\kod\pg-api> node --env-file=.env deneme.js[ { mesaj: 'Merhaba Postgres', toplam: 5 } ]

• pool.query(...) sorguyu gönderir ve bir Promise döndürür; await sonucu bekler (Ders 15).
• sonuc.rows: gelen satırlar, her biri bir obje. Sütun adları objenin anahtarları oldu: AS mesaj yazdığın için anahtar mesaj.
• await pool.end(): havuzu kapatır. Bu satırı silip denediğimizde program sonucu hemen yazdı ama ancak 10 saniye kadar sonra kapandı: havuz boştaki bağlantıyı 10 saniye açık tutar. Tek seferlik betiklerde pool.end() yaz. Sunucuda (app.js) yazmayacaksın; sunucu kapanmaz, havuz da açık kalmalı.

#Sonuç objesi

Şimdi gerçek tabloyu sorgula. deneme.js'deki sorguyu şununla değiştir:

1import { pool } from "./db.js"2 3const sonuc = await pool.query("SELECT id, ad, bolge FROM oyuncular WHERE bolge = 'TR'")4console.log(sonuc.rows)5console.log(sonuc.rowCount)6console.log(sonuc.command)7console.log(sonuc.fields.map((alan) => alan.name))8await pool.end()

[  { id: 1, ad: 'Deniz', bolge: 'TR' },  { id: 2, ad: 'Ece', bolge: 'TR' },  { id: 4, ad: 'Selin', bolge: 'TR' }]3SELECT[ 'id', 'ad', 'bolge' ]

Çoğu zaman yalnız rows lazım olur; o yüzden sık sık parçalayarak yazacaksın: const { rows } = await pool.query(...) (Ders 12).

1import { pool } from "./db.js"2 3const sonuc = pool.query("SELECT id, ad FROM oyuncular")4console.log(sonuc.rows.length)

PS C:\kod\pg-api> node --env-file=.env deneme.jsfile:///C:/kod/pg-api/deneme.js:4console.log(sonuc.rows.length)                       ^ TypeError: Cannot read properties of undefined (reading 'length')    at file:///C:/kod/pg-api/deneme.js:4:24    ...

#Bağlanamazsan

İlk bağlantı her zaman ilk denemede kurulmaz. Mesaj ne olursa olsun önce en alttaki at async file:///...deneme.js:3:15 satırına bak: hatanın senin kodunda hangi satırdan çıktığını o söyler. En üstteki pg-pool\index.js:45 satırı paketin içi; orada düzeltilecek bir şey yok.

PS C:\kod\pg-api> node deneme.jsC:\kod\pg-api\node_modules\pg-pool\index.js:45    Error.captureStackTrace(err)          ^ AggregateError [ECONNREFUSED]:     at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/deneme.js:3:15 {  code: 'ECONNREFUSED',  [errors]: [    Error: connect ECONNREFUSED ::1:5432    ...    Error: connect ECONNREFUSED 127.0.0.1:5432    ...  ]} Node.js v24.20.0

PS C:\kod\pg-api> node --env-file=.env deneme.jsC:\kod\pg-api\node_modules\pg-pool\index.js:45    Error.captureStackTrace(err)          ^ error: password authentication failed for user "neondb_owner"    at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/deneme.js:3:15 {  length: 108,  severity: 'FATAL',  code: '28P01',  ...}

PS C:\kod\pg-api> node --env-file=.env deneme.jsC:\kod\pg-api\node_modules\pg-pool\index.js:45    Error.captureStackTrace(err)          ^ Error: getaddrinfo ENOTFOUND ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tch    at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/deneme.js:3:15 {  errno: -3008,  code: 'ENOTFOUND',  syscall: 'getaddrinfo',  hostname: 'ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tch'}

PS C:\kod\pg-api> node --env-file=.env deneme.jsC:\kod\pg-api\node_modules\pg-pool\index.js:45    Error.captureStackTrace(err)          ^ Error: The server does not support SSL connections    at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/deneme.js:3:15 Node.js v24.20.0

#Satırlar JSON olur

Şimdi sorguyu bir uç noktaya taşı. Proje klasöründe app.js'i aç:

1import express from "express"2import { pool } from "./db.js"3 4const app = express()5const port = process.env.PORT || 30006app.use(express.json())7 8app.get("/oyuncular", async (req, res) => {9    const { rows } = await pool.query("SELECT id, ad, bolge FROM oyuncular ORDER BY id")10    res.json(rows)11})12 13app.listen(port, () => {14    console.log(`API hazır: http://localhost:${port}`)15})

Express kısmı Ders 28'deki gibi; yeni olan tek satır pool.query. process.env.PORT || 3000 ise "barındırıcı bir port verdiyse onu, vermediyse 3000'i kullan" demek. Sunucuyu başlat, sonra ikinci bir terminal açıp (Ders 27) iste:

PS C:\kod\pg-api> npm run dev > pg-api@1.0.0 dev> node --watch --env-file=.env app.js API hazır: http://localhost:3000

PS C:\kod\pg-api> curl.exe http://localhost:3000/oyuncular[{"id":1,"ad":"Deniz","bolge":"TR"},{"id":2,"ad":"Ece","bolge":"TR"},{"id":3,"ad":"Mert","bolge":"EUW"},{"id":4,"ad":"Selin","bolge":"TR"},{"id":5,"ad":"Kaan","bolge":"EUW"}]

Tablo artık bir uç noktada. res.json(rows) diziyi JSON.stringify ile metne çevirip Content-Type: application/json; charset=utf-8 başlığıyla gönderir (Ders 28). Satırlar zaten düz objeler olduğu için başka bir şey yapman gerekmedi. Ama her sütun bu kadar uysal değil.

#Tipler: Postgres'ten JavaScript'e

deneme.js'de maçları özetleyen bir sorgu dene:

1import { pool } from "./db.js"2 3const sonuc = await pool.query("SELECT count(*) AS mac, avg(kill) AS ortalama, max(tarih) AS son FROM maclar")4console.log(sonuc.rows)5console.log(JSON.stringify(sonuc.rows))6await pool.end()

[  {    mac: '7',    ortalama: '6.4285714285714286',    son: 2026-10-11T17:02:39.352Z  }][{"mac":"7","ortalama":"6.4285714285714286","son":"2026-10-11T17:02:39.352Z"}]

mac ve ortalama tek tırnak içinde: sayı değil, metin. son ise tırnaksız ama bir sayı da değil; bir Date objesi. JSON.stringify onu metne çevirdi. Saatin sonundaki Z saatin UTC olduğunu söyler; Türkiye saati üç saat ileridedir. pg her Postgres tipini şöyle karşılar:

Neden metin? JavaScript'in sayıları 9.007.199.254.740.991'den büyük tam sayıları kesin tutamaz; bigint ise 9.223.372.036.854.775.807'ye kadar gider. numeric de istediğin kadar basamak tutabilir; JavaScript sayısına çevirmek basamak kaybettirebilir (Ders 9'daki ondalık tuzağı). pg veriyi sessizce bozmaktansa metin olarak verir; sayıya çevirip çevirmemek senin kararın.

Bunun API'de ne demek olduğunu gör. Oyuncu başına maç sayısı ve ortalama kill veren bir uç nokta ekle; LEFT JOIN maçı olmayan Kaan'ı da listeye katar (Ders 36). Bu dersteki yeni route'ların hepsini app.listen'ın üstüne ekle; kod bloklarındaki satır numaraları dosyanın o anki hâlini gösteriyor:

13app.get("/istatistik", async (req, res) => {14    const { rows } = await pool.query(`15        SELECT o.ad, count(m.id) AS mac, round(avg(m.kill), 1) AS ortalama_kill16        FROM oyuncular o17        LEFT JOIN maclar m ON m.oyuncu_id = o.id18        GROUP BY o.id, o.ad19        ORDER BY o.id20    `)21    res.json(rows)22})

PS C:\kod\pg-api> curl.exe http://localhost:3000/istatistik[{"ad":"Deniz","mac":"3","ortalama_kill":"7.0"},{"ad":"Ece","mac":"2","ortalama_kill":"9.0"},{"ad":"Mert","mac":"1","ortalama_kill":"2.0"},{"ad":"Selin","mac":"1","ortalama_kill":"4.0"},{"ad":"Kaan","mac":"0","ortalama_kill":null}]

Uzun SQL'i ters tırnakla yazdık; ters tırnaklı metin birden çok satıra yayılabilir (Ders 9). Yanıttaki her sayı tırnak içinde. Bu API'yi kullanan biri mac + 1 hesaplarsa "31" elde eder (Ders 1'deki metin + sayı tuzağı). Düzeltmenin en temiz yeri SQL'in kendisi:

13app.get("/istatistik", async (req, res) => {14    const { rows } = await pool.query(`15        SELECT o.ad, count(m.id)::int AS mac,16               round(avg(m.kill), 1)::float AS "ortalamaKill"17        FROM oyuncular o18        LEFT JOIN maclar m ON m.oyuncu_id = o.id19        GROUP BY o.id, o.ad20        ORDER BY o.id21    `)22    res.json(rows)23})

PS C:\kod\pg-api> curl.exe http://localhost:3000/istatistik[{"ad":"Deniz","mac":3,"ortalamaKill":7},{"ad":"Ece","mac":2,"ortalamaKill":9},{"ad":"Mert","mac":1,"ortalamaKill":2},{"ad":"Selin","mac":1,"ortalamaKill":4},{"ad":"Kaan","mac":0,"ortalamaKill":null}]

• :: Postgres'te tip çevirme işaretidir: count(m.id)::int "sonucu integer yap" demek. Bir oyuncunun maç sayısı integer'a rahatça sığar.
• ::float ondalıklı sayıyı JavaScript sayısına uyan bir tipe (double precision) çevirir. İstatistikte birkaç basamak kaybı sorun değil; para gibi kuruşun önemli olduğu yerde numeric'i metin olarak bırak.
• AS "ortalamaKill": JSON'daki anahtarın adı. SQL'de sütunlar snake_case, JavaScript'te adlar camelCase yazılır; takma ad (Ders 34) ikisini buluşturur.
• Kaan'ın ortalaması null: hiç maçı yok, avg boş gruba NULL verir. Ona 0 demek yanlış olurdu; null "bilinmiyor" demek.

1import { pool } from "./db.js"2 3const sonuc = await pool.query("SELECT oyuncu_id AS "oyuncuId", sampiyon FROM maclar LIMIT 1")4console.log(sonuc.rows)5await pool.end()

PS C:\kod\pg-api> node --env-file=.env deneme.jsfile:///C:/kod/pg-api/deneme.js:3const sonuc = await pool.query("SELECT oyuncu_id AS "oyuncuId", sampiyon FROM maclar LIMIT 1")                               ^^^^^^^^^^^^^^^^^^^^^^ SyntaxError: missing ) after argument list    ...

#Havuz: bağlantıları paylaşmak

Postgres'e bağlanmak ucuz bir iş değil. Bağlantı açılınca iki taraf önce tanışır: trafik TLS ile şifrelenir, kullanıcı adıyla şifre denetlenir, ayarlar paylaşılır. Bu tanışmaya el sıkışma (handshake) denir. node-postgres'in belgesine göre el sıkışma tek başına 20–30 milisaniye sürebilir; Neon başka bir ülkedeki bir sunucudaysa süre uzar.

Üstelik veritabanı aynı anda sınırlı sayıda bağlantı kabul eder: Neon'da havuzsuz bağlantı sınırı, makinenin boyuna göre yaklaşık 100 ile 4.000 arasında.

Her istekte yeni bağlantı açıp kapatmak hem yavaş hem israf. Bağlantı havuzu (connection pool) birkaç bağlantıyı açık tutar ve gelen sorgulara sırayla ödünç verir. Pool bağlantıları gerektikçe açar; varsayılan olarak en çok 10 tane açar ve 10 saniye boşta kalan bağlantıyı kapatır.

Havuzu kullanmanın iki yolu var:

• pool.query(...): boştaki bir bağlantıyı alır, sorguyu çalıştırır, bağlantıyı geri verir. Tek bir sorgu için hep bunu kullan.
• pool.connect() ile client.release(): bağlantıyı sen alırsın, birden çok sorguyu aynı bağlantıda çalıştırırsın ve işin bitince geri verirsin. Transaction için gerekir, çünkü BEGIN, sorgular ve COMMIT aynı bağlantıda olmalı. Göç bölümünde kullanacaksın.

Havuzun iki klasik yanlış kullanımı var. İkisi de ilk denemede çalışır, yük gelince çöker.

8app.get("/oyuncular", async (req, res) => {9    const pool = new Pool({ connectionString: process.env.DATABASE_URL })10    const { rows } = await pool.query("SELECT id, ad, bolge FROM oyuncular ORDER BY id")11    res.json(rows)12})

PS C:\kod\pg-api> (1..20 | ForEach-Object { curl.exe -s -o NUL -w "%{http_code}" http://localhost:3000/oyuncular }) -join " "200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 500 500 500

error: remaining connection slots are reserved for roles with the SUPERUSER attribute    ...  severity: 'FATAL',  code: '53300',  ...

8app.get("/oyuncular", async (req, res) => {9    const client = await pool.connect()10    const { rows } = await client.query("SELECT id, ad, bolge FROM oyuncular ORDER BY id")11    res.json(rows)12})

PS C:\kod\pg-api> (1..10 | ForEach-Object { curl.exe -s -o NUL -w "%{http_code}" http://localhost:3000/oyuncular }) -join " "200 200 200 200 200 200 200 200 200 200PS C:\kod\pg-api> curl.exe --max-time 8 http://localhost:3000/oyuncularcurl: (28) Operation timed out after 8008 milliseconds with 0 bytes received

8app.get("/oyuncular", async (req, res) => {9    const client = await pool.connect()10    try {11        const { rows } = await client.query("SELECT id, ad, bolge FROM oyuncular ORDER BY id")12        res.json(rows)13    } finally {14        client.release()15    }16})

#Sağlam bir db.js

Gördüğün iki hatayı ve henüz görmediğin bir üçüncüsünü db.js'e eklenen birkaç satırla daha anlaşılır hâle getirebilirsin:

1import { Pool } from "pg"2 3if (!process.env.DATABASE_URL) {4    throw new Error("DATABASE_URL tanımlı değil: node --env-file=.env ile mi çalıştırdın?")5}6 7export const pool = new Pool({8    connectionString: process.env.DATABASE_URL,9    connectionTimeoutMillis: 500010})11 12pool.on("error", (hata) => {13    console.error("Havuzdaki boşta bekleyen bir bağlantı koptu:", hata.message)14})

3–5. satırlar: erken ve açık hata (Ders 13). --env-file'ı unutursan artık kafa karıştıran ECONNREFUSED ::1:5432 yerine ne yapman gerektiğini söyleyen bir mesaj alırsın:

PS C:\kod\pg-api> node deneme.jsfile:///C:/kod/pg-api/db.js:4    throw new Error("DATABASE_URL tanımlı değil: node --env-file=.env ile mi çalıştırdın?")          ^ Error: DATABASE_URL tanımlı değil: node --env-file=.env ile mi çalıştırdın?    at file:///C:/kod/pg-api/db.js:4:11    ...

9. satır: bekleme sınırı. connectionTimeoutMillis: 5000, bir bağlantı için en çok 5 saniye beklenmesini söyler: havuzdan boş bir bağlantının gelmesi de, yeni bir bağlantının kurulması da bu sürede bitmeli. Varsayılan değer 0, yani "sonsuza kadar bekle". release unutulmuş uygulamada 11. istek artık donmaz; 5 saniye kadar sonra 500 döner ve sunucunun terminali sebebini yazar:

Error: timeout exceeded when trying to connect    at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at async file:///C:/kod/pg-api/app.js:9:20

Mesaj "bağlanmaya çalışırken süre doldu" diyor, ama asıl sebep çoğu zaman ağ değil, geri verilmemiş bağlantılardır. Bu mesajı görünce önce pool.connect() geçen satırlara bak.

12–14. satırlar: boştaki bağlantının kopması. Havuz bağlantıları açık tutar ve o sırada sen hiçbir şey yapmazken bağlantı kopabilir: veritabanı yeniden başlatılabilir, ağ gidip gelebilir. Havuz bunu bir error olayıyla bildirir (Ders 22'deki olaylar gibi). Dinleyen yoksa Node bütün programı kapatır.

1import { pool } from "./db.js"2 3await pool.query("SELECT 1")4console.log("Sorgu bitti, bağlantı havuzda bekliyor")5setTimeout(() => console.log("Program hâlâ çalışıyor"), 3000)

PS C:\kod\pg-api> node --env-file=.env bekle.jsSorgu bitti, bağlantı havuzda bekliyornode:events:505    throw er; // Unhandled 'error' event    ^ error: terminating connection due to administrator command    ...Emitted 'error' event on BoundPool instance at:  ...  code: '57P01',  ... Node.js v24.20.0

PS C:\kod\pg-api> node --env-file=.env bekle.jsSorgu bitti, bağlantı havuzda bekliyorHavuzdaki boşta bekleyen bir bağlantı koptu: terminating connection due to administrator commandProgram hâlâ çalışıyor

#SQL injection: kullanıcının yazdığı metin

Ders 34'te SQL Editor'de ' OR '1'='1'in bütün satırları açtığını gördün; bu saldırının adını da Ders 31'de öğrenmiştin: SQL injection (Ders 31). Şimdi aynı hatayı gerçek bir API'de yapıp sonucunu göreceksin. Oyuncuyu adıyla arayan bir uç nokta ekle; şablon metinle (Ders 9), ilk akla gelen yoldan:

25app.get("/ara", async (req, res) => {26    const sql = `SELECT id, ad, bolge FROM oyuncular WHERE ad = '${req.query.ad}'`27    console.log(sql)28    const { rows } = await pool.query(sql)29    res.json(rows)30})

Önce masum bir istek, sonra adı bir SQL parçası olan bir istek. Adreste boşluk olamaz; %20 boşluğun adresteki yazılışıdır. PowerShell ' ve ; işaretlerini kendisi yorumlamasın diye adresi çift tırnağa al:

PS C:\kod\pg-api> curl.exe "http://localhost:3000/ara?ad=Deniz"[{"id":1,"ad":"Deniz","bolge":"TR"}]PS C:\kod\pg-api> curl.exe "http://localhost:3000/ara?ad=x'%20OR%20'1'='1"[{"id":1,"ad":"Deniz","bolge":"TR"},{"id":2,"ad":"Ece","bolge":"TR"},{"id":3,"ad":"Mert","bolge":"EUW"},{"id":4,"ad":"Selin","bolge":"TR"},{"id":5,"ad":"Kaan","bolge":"EUW"}]

SELECT id, ad, bolge FROM oyuncular WHERE ad = 'Deniz'SELECT id, ad, bolge FROM oyuncular WHERE ad = 'x' OR '1'='1'

İkinci istekte kullanıcı bir ad değil, SQL yazdı. Şablon metin onu tırnakların arasına olduğu gibi yapıştırdı ve sorgunun anlamı değişti. Postgres'e giden sorgu şuydu; SQL Editor'de çalıştırırsan aynı beş satır gelir:

SELECT id, ad, bolge FROM oyuncular WHERE ad = 'x' OR '1'='1';

Daha kötüsü de var. pg, parametresiz bir sorgu metninde noktalı virgülle ayrılmış birden çok komut görürse hepsini sırayla çalıştırır. -- ise SQL'de yorum başlatır ve sondaki fazla tırnağı etkisiz bırakır:

PS C:\kod\pg-api> curl.exe -i "http://localhost:3000/ara?ad=x';%20DELETE%20FROM%20maclar;%20--"HTTP/1.1 200 OKX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Date: Sun, 11 Oct 2026 17:03:32 GMTConnection: keep-aliveKeep-Alive: timeout=5Content-Length: 0 PS C:\kod\pg-api> curl.exe http://localhost:3000/istatistik[{"ad":"Deniz","mac":0,"ortalamaKill":null},{"ad":"Ece","mac":0,"ortalamaKill":null},{"ad":"Mert","mac":0,"ortalamaKill":null},{"ad":"Selin","mac":0,"ortalamaKill":null},{"ad":"Kaan","mac":0,"ortalamaKill":null}]

SELECT id, ad, bolge FROM oyuncular WHERE ad = 'x'; DELETE FROM maclar; --'

Yanıt boş bir 200 OK: hata yok, alarm yok. (Gövde boş, çünkü pg birden çok komut çalıştırınca her komut için bir sonuç içeren bir dizi döndürür; dizinin rows alanı olmadığı için res.json'a undefined gitti.) Ama maclar tablosunun bütün satırları silindi. Bunu kendi veritabanında denediysen maçları geri getirmek için veri.sql'deki ikinci INSERT'i SQL Editor'de yeniden çalıştır. Bu denemeleri yalnız kendi veritabanında yap; başkasının sisteminde denemek suçtur.

#Parametreli sorgu: $1, $2

Çözüm, kullanıcının değerini sorgu metnine hiç koymamak. Metinde değerin yerine bir yer tutucu ($1) yazarsın, değeri ayrı bir dizide verirsin:

25app.get("/ara", async (req, res) => {26    const { rows } = await pool.query(27        "SELECT id, ad, bolge FROM oyuncular WHERE ad = $1",28        [req.query.ad]29    )30    res.json(rows)31})

PS C:\kod\pg-api> curl.exe "http://localhost:3000/ara?ad=Deniz"[{"id":1,"ad":"Deniz","bolge":"TR"}]PS C:\kod\pg-api> curl.exe "http://localhost:3000/ara?ad=x'%20OR%20'1'='1"[]PS C:\kod\pg-api> curl.exe "http://localhost:3000/ara?ad=x';%20DELETE%20FROM%20maclar;%20--"[]PS C:\kod\pg-api> curl.exe http://localhost:3000/istatistik[{"ad":"Deniz","mac":3,"ortalamaKill":7},{"ad":"Ece","mac":2,"ortalamaKill":9},{"ad":"Mert","mac":1,"ortalamaKill":2},{"ad":"Selin","mac":1,"ortalamaKill":4},{"ad":"Kaan","mac":0,"ortalamaKill":null}]

İki saldırı da boş bir dizi döndürdü ve maçlar yerinde.

pg artık sorguyu iki ayrı parça hâlinde gönderiyor: önce yer tutuculu SQL metni, sonra değerler. Postgres metni değerlerden önce okur ve ne yapacağına karar verir; değer geldiğinde komut çoktan bellidir. x' OR '1'='1 artık yalnızca adı tuhaf bir oyuncu arayan bir metin. Böyle bir oyuncu yok, sonuç boş.

Dört kural:

• Numaralar diziyle eşleşir: $1 dizinin ilk elemanı, $2 ikincisi. Sırayı karıştırırsan değerler yanlış sütunlara gider.
• Yer tutucuyu tırnağa koyma. '$1' artık bir yer tutucu değil, içinde dolar işareti olan bir metindir (aşağıdaki hata kartı).
• Yalnız değerler parametre olabilir. Tablo ya da sütun adı, ASC ya da DESC gibi SQL parçaları olamaz; onları izin verdiğin seçenekler arasından kendin seçersin (Görev 4).
• Şablon metin parametre değildir. Ters tırnak ve ${} metni birleştirir; korumaz.

pool.query(`SELECT id, ad FROM oyuncular WHERE ad = '${ad}'`)

pool.query("SELECT id, ad FROM oyuncular WHERE ad = $1", [ad])

Aynı fikirle tek bir oyuncuyu getiren uç noktayı yaz. Adresteki :id her zaman metin gelir (Ders 28); onu sayıya çevirmene gerek yok, Postgres $1'i sütunun tipine (integer) göre okur:

33app.get("/oyuncular/:id", async (req, res) => {34    const { rows } = await pool.query(35        "SELECT id, ad, bolge FROM oyuncular WHERE id = $1",36        [req.params.id]37    )38    if (rows.length === 0) {39        return res.status(404).json({ hata: "Oyuncu bulunamadı" })40    }41    res.json(rows[0])42})

PS C:\kod\pg-api> curl.exe http://localhost:3000/oyuncular/3{"id":3,"ad":"Mert","bolge":"EUW"}PS C:\kod\pg-api> curl.exe http://localhost:3000/oyuncular/99{"hata":"Oyuncu bulunamadı"}

Satır gelmezse rows boş bir dizidir, rows[0] ise undefined. undefined'ı JSON'a çevirmek yerine 404 döndürüyoruz. Tek satır beklediğin her yerde bu iki satırlık kalıbı kullanacaksın.

1import { pool } from "./db.js"2 3const ad = "Deniz"4const { rows } = await pool.query("SELECT id, ad FROM oyuncular WHERE ad = '$1'", [ad])5console.log(rows)6await pool.end()

PS C:\kod\pg-api> node --env-file=.env deneme.jsC:\kod\pg-api\node_modules\pg-pool\index.js:45    Error.captureStackTrace(err)          ^ error: bind message supplies 1 parameters, but prepared statement "" requires 0    at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/deneme.js:4:18 {  length: 137,  severity: 'ERROR',  code: '08P01',  ...}

PS C:\kod\pg-api> curl.exe -i http://localhost:3000/oyuncular/abcHTTP/1.1 500 Internal Server ErrorX-Powered-By: ExpressContent-Security-Policy: default-src 'none'X-Content-Type-Options: nosniffContent-Type: text/html; charset=utf-8... <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Error</title></head><body><pre>error: invalid input syntax for type integer: &quot;abc&quot;<br> &nbsp; &nbsp;at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11<br> ...</pre></body></html>

#Yazmak ve hata kodlarını çevirmek

Şimdi oyuncu ekleyen uç noktayı yaz. INSERT ... RETURNING (Ders 35) Postgres'in verdiği id ile birlikte yeni satırı geri döndürür:

44app.post("/oyuncular", async (req, res) => {45    const { ad, bolge } = req.body46    const { rows } = await pool.query(47        "INSERT INTO oyuncular (ad, bolge) VALUES ($1, $2) RETURNING id, ad, bolge",48        [ad, bolge]49    )50    res.status(201).json(rows[0])51})

İsteğin gövdesini Ders 27'deki gibi bir dosyadan gönder. VS Code'da arda.json dosyasına { "ad": "Arda", "bolge": "TR" }, deniz.json dosyasına { "ad": "Deniz", "bolge": "TR" } yaz:

PS C:\kod\pg-api> curl.exe -i --json "@arda.json" http://localhost:3000/oyuncularHTTP/1.1 201 CreatedX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 33... {"id":6,"ad":"Arda","bolge":"TR"}PS C:\kod\pg-api> curl.exe -i --json "@deniz.json" http://localhost:3000/oyuncularHTTP/1.1 500 Internal Server ErrorX-Powered-By: ExpressContent-Security-Policy: default-src 'none'X-Content-Type-Options: nosniffContent-Type: text/html; charset=utf-8... <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Error</title></head><body><pre>error: duplicate key value violates unique constraint &quot;oyuncular_ad_key&quot;<br> &nbsp; &nbsp;at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11<br> ...</pre></body></html>

Arda eklendi. Deniz zaten var; UNIQUE kısıtı ikinci Deniz'i reddetti ve istemci yine yığın izli bir 500 aldı. Sunucunun terminali hatanın bütün alanlarını yazdı:

error: duplicate key value violates unique constraint "oyuncular_ad_key"    at C:\kod\pg-api\node_modules\pg-pool\index.js:45:11    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/app.js:46:22 {  length: 200,  severity: 'ERROR',  code: '23505',  detail: 'Key (ad)=(Deniz) already exists.',  hint: undefined,  ...  schema: 'public',  table: 'oyuncular',  ...  constraint: 'oyuncular_ad_key',  ...}

Bu bir obje ve alanlarını kodda okuyabilirsin: hata.code, hata.detail, hata.table, hata.constraint. En önemlisi code.

Bir API'nin işi, veritabanının dilini istemcinin diline çevirmektir. Sık göreceğin kodlar ve karşılıkları:

409 Conflict'i Ders 26'da tanıdın, Ders 31'de alınmış bir kullanıcı adı için kendin de döndürdün: "İstek düzgün yazılmış ama sunucudaki mevcut durumla çakışıyor" demek. İkinci Deniz, var olan Deniz'le çakışır; istemci adı değiştirirse aynı istek geçer. 23503'ün iki yüzü var: maça olmayan bir oyuncuyu yazmak istemcinin hatasıdır (400); maçı olan bir oyuncuyu silmek ise mevcut durumla çakışmadır (409).

Çeviriyi ayrı bir dosyada, tek başına denenebilen bir fonksiyon olarak yaz (Ders 6'daki "her parçayı ayrı dene" alışkanlığı). hatalar.js adında bir dosya aç:

1export function pgHatasiniCevir(hata, metot) {2    if (hata.code === "23505") {3        return { durum: 409, mesaj: "Bu kayıt zaten var" }4    }5    if (hata.code === "23503") {6        if (metot === "DELETE") {7            return { durum: 409, mesaj: "Bu kayda bağlı başka kayıtlar var" }8        }9        return { durum: 400, mesaj: "Bağlandığı kayıt bulunamadı" }10    }11    if (hata.code === "22P02" || hata.code === "23502" || hata.code === "23514") {12        return { durum: 400, mesaj: "Gönderilen değerlerden biri geçersiz" }13    }14    return null15}16 17console.log(pgHatasiniCevir({ code: "23505" }, "POST"))18console.log(pgHatasiniCevir({ code: "23503" }, "POST"))19console.log(pgHatasiniCevir({ code: "23503" }, "DELETE"))20console.log(pgHatasiniCevir({ code: "22P02" }, "GET"))21console.log(pgHatasiniCevir({ code: "42P01" }, "GET"))

{ durum: 409, mesaj: 'Bu kayıt zaten var' }{ durum: 400, mesaj: 'Bağlandığı kayıt bulunamadı' }{ durum: 409, mesaj: 'Bu kayda bağlı başka kayıtlar var' }{ durum: 400, mesaj: 'Gönderilen değerlerden biri geçersiz' }null

node hatalar.js ile çalıştır. Fonksiyon yalnız tanıdığı kodları çevirir, tanımadığına null döndürür. 42P01 "tablo yok" demek: bu istemcinin değil, kodun hatası; 500 kalmalı. Denedikten sonra alttaki beş console.log satırını sil; dosyada yalnız fonksiyon kalsın.

Şimdi fonksiyonu Express'in hata yakalayıcısına bağla. app.js'in en üstüne içe aktarmayı ekle:

1import express from "express"2import { pool } from "./db.js"3import { pgHatasiniCevir } from "./hatalar.js"

app.listen'ın hemen üstüne de silme uç noktasını ve hata yakalayıcıyı ekle:

54app.delete("/oyuncular/:id", async (req, res) => {55    const { rowCount } = await pool.query("DELETE FROM oyuncular WHERE id = $1", [req.params.id])56    if (rowCount === 0) {57        return res.status(404).json({ hata: "Oyuncu bulunamadı" })58    }59    res.status(204).end()60})61 62app.use((hata, req, res, next) => {63    const cevap = pgHatasiniCevir(hata, req.method)64    if (cevap) {65        return res.status(cevap.durum).json({ hata: cevap.mesaj })66    }67    if (hata.status) {68        return res.status(hata.status).json({ hata: hata.message })69    }70    console.error(hata)71    res.status(500).json({ hata: "Sunucuda bir hata oluştu" })72})

• rowCount: DELETE'in sildiği satır sayısı. 0 ise öyle bir oyuncu yok: 404. Silme başarılıysa gövdesiz 204 No Content (Ders 26).
• Dört parametreli app.use, Express'in hata yakalayıcısıdır (Ders 28). Express 5'te bir async route'un içinden fırlayan hata, try/catch yazmana gerek kalmadan buraya gelir. Bütün route'lardan sonra, app.listen'ın üstüne yazılır.
• hata.status: express.json(), bozuk bir gövdeyi 400 durumlu bir hatayla bildirir; onu olduğu gibi geçiriyoruz.
• Geri kalan her şey gerçekten sunucunun sorunudur: ayrıntıyı console.error ile terminale yaz, istemciye yalnız genel bir cümle gönder.

Dene. bolgesiz.json dosyasına { "ad": "Zeynep" } yaz; --json "Deniz" ise JSON olmayan bir gövde gönderir:

PS C:\kod\pg-api> curl.exe -i --json "@deniz.json" http://localhost:3000/oyuncularHTTP/1.1 409 ConflictX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 30... {"hata":"Bu kayıt zaten var"}PS C:\kod\pg-api> curl.exe --json "@bolgesiz.json" http://localhost:3000/oyuncular{"hata":"Gönderilen değerlerden biri geçersiz"}PS C:\kod\pg-api> curl.exe --json "Deniz" http://localhost:3000/oyuncular{"hata":"Unexpected token 'D', \"Deniz\" is not valid JSON"}PS C:\kod\pg-api> curl.exe http://localhost:3000/oyuncular/abc{"hata":"Gönderilen değerlerden biri geçersiz"}PS C:\kod\pg-api> curl.exe -i -X DELETE http://localhost:3000/oyuncular/1HTTP/1.1 409 ConflictX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 48... {"hata":"Bu kayda bağlı başka kayıtlar var"}PS C:\kod\pg-api> curl.exe -i -X DELETE http://localhost:3000/oyuncular/5HTTP/1.1 204 No ContentX-Powered-By: Express... PS C:\kod\pg-api> curl.exe -X DELETE http://localhost:3000/oyuncular/5{"hata":"Oyuncu bulunamadı"}

Her hata artık doğru kodla ve anlaşılır bir cümleyle dönüyor. Deniz'in maçları olduğu için silinemedi (409); maçı olmayan Kaan silindi (204); ikinci silme isteği onu bulamadı (404).

app.js'in son hâli, karşılaştırmak için:

1import express from "express"2import { pool } from "./db.js"3import { pgHatasiniCevir } from "./hatalar.js"4 5const app = express()6const port = process.env.PORT || 30007app.use(express.json())8 9app.get("/oyuncular", async (req, res) => {10    const { rows } = await pool.query("SELECT id, ad, bolge FROM oyuncular ORDER BY id")11    res.json(rows)12})13 14app.get("/istatistik", async (req, res) => {15    const { rows } = await pool.query(`16        SELECT o.ad, count(m.id)::int AS mac,17               round(avg(m.kill), 1)::float AS "ortalamaKill"18        FROM oyuncular o19        LEFT JOIN maclar m ON m.oyuncu_id = o.id20        GROUP BY o.id, o.ad21        ORDER BY o.id22    `)23    res.json(rows)24})25 26app.get("/ara", async (req, res) => {27    const { rows } = await pool.query(28        "SELECT id, ad, bolge FROM oyuncular WHERE ad = $1",29        [req.query.ad]30    )31    res.json(rows)32})33 34app.get("/oyuncular/:id", async (req, res) => {35    const { rows } = await pool.query(36        "SELECT id, ad, bolge FROM oyuncular WHERE id = $1",37        [req.params.id]38    )39    if (rows.length === 0) {40        return res.status(404).json({ hata: "Oyuncu bulunamadı" })41    }42    res.json(rows[0])43})44 45app.post("/oyuncular", async (req, res) => {46    const { ad, bolge } = req.body47    const { rows } = await pool.query(48        "INSERT INTO oyuncular (ad, bolge) VALUES ($1, $2) RETURNING id, ad, bolge",49        [ad, bolge]50    )51    res.status(201).json(rows[0])52})53 54app.delete("/oyuncular/:id", async (req, res) => {55    const { rowCount } = await pool.query("DELETE FROM oyuncular WHERE id = $1", [req.params.id])56    if (rowCount === 0) {57        return res.status(404).json({ hata: "Oyuncu bulunamadı" })58    }59    res.status(204).end()60})61 62app.use((hata, req, res, next) => {63    const cevap = pgHatasiniCevir(hata, req.method)64    if (cevap) {65        return res.status(cevap.durum).json({ hata: cevap.mesaj })66    }67    if (hata.status) {68        return res.status(hata.status).json({ hata: hata.message })69    }70    console.error(hata)71    res.status(500).json({ hata: "Sunucuda bir hata oluştu" })72})73 74app.listen(port, () => {75    console.log(`API hazır: http://localhost:${port}`)76})

#Şema dosyası ve göç (migration)

Uygulama büyüdükçe tablolar da değişir. Diyelim ki oyuncuların seviyesini de tutmak istiyorsun. schema.sql'e bir sütun eklemek yetmez: Neon'daki tablo zaten kurulu ve içinde veri var. Dosyayı yeniden çalıştırırsan Postgres reddeder:

CREATE TABLE oyuncular (    id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,    ad text NOT NULL UNIQUE,    bolge text NOT NULL);

ERROR:  relation "oyuncular" already exists

Tabloyu silip yeniden kurmak verini götürür. SQL Editor'de elle ALTER TABLE çalıştırmak ise iz bırakmaz: üç ay sonra canlı veritabanında hangi değişikliğin yapıldığını, takım arkadaşının veritabanında neyin eksik olduğunu kimse bilemez. Çözüm, her değişikliği numaralı bir dosyaya yazmak ve bu dosyaları sırayla, her birini bir kez çalıştırmak.

Projende goclar adında bir klasör aç. İlk iki göç: oyunculara seviye sütunu ekle ve maçları oyuncuya göre arayan sorgular hızlansın diye oyuncu_id'ye indeks koy (Ders 36):

1ALTER TABLE oyuncular ADD COLUMN seviye integer NOT NULL DEFAULT 1 CHECK (seviye >= 1);

1CREATE INDEX maclar_oyuncu_id_idx ON maclar (oyuncu_id);

Adların başındaki sıfırlı numaralar sırayı belirler. Metinler harf harf karşılaştırılarak sıralanır (Ders 11); 1_..., 2_..., 10_... diye yazsaydın .sort() onları 10_, 1_, 2_ sırasına koyardı. Şimdi bu dosyaları uygulayan küçük betiği yaz:

1import { readdir, readFile } from "node:fs/promises"2import { pool } from "./db.js"3 4await pool.query(`5    CREATE TABLE IF NOT EXISTS goc_gecmisi (6        dosya text PRIMARY KEY,7        uygulandi timestamptz NOT NULL DEFAULT now()8    )9`)10 11const { rows } = await pool.query("SELECT dosya FROM goc_gecmisi")12const uygulananlar = rows.map((satir) => satir.dosya)13const dosyalar = (await readdir("goclar")).filter((ad) => ad.endsWith(".sql")).sort()14 15for (const dosya of dosyalar) {16    if (uygulananlar.includes(dosya)) {17        continue18    }19    const sql = await readFile(`goclar/${dosya}`, "utf8")20    const client = await pool.connect()21    try {22        await client.query("BEGIN")23        await client.query(sql)24        await client.query("INSERT INTO goc_gecmisi (dosya) VALUES ($1)", [dosya])25        await client.query("COMMIT")26        console.log("Uygulandı:", dosya)27    } catch (hata) {28        await client.query("ROLLBACK")29        throw hata30    } finally {31        client.release()32    }33}34 35console.log("Göçler tamam.")36await pool.end()

• 4–9. satırlar: goc_gecmisi tablosunu kurar. IF NOT EXISTS "yoksa kur, varsa dokunma" demek; betik her çalıştığında hata vermeden geçer.
• 11–13. satırlar: uygulanmış dosyaların adlarını tablodan, klasördeki .sql dosyalarını diskten okur (Ders 29) ve ada göre sıralar (Ders 11).
• 16–18. satırlar: tabloda adı olan dosyayı atlar. Her göç bir kez çalışır.
• 20–32. satırlar: göç dosyası ve onun kaydı tek bir transaction içinde, aynı bağlantıda çalışır: ya ikisi birden olur ya hiçbiri. Bunun için pool.connect() gerekiyor. pool.query("BEGIN") yazsaydın havuz BEGIN'i bir bağlantıya, sonraki sorguyu başka bir bağlantıya verebilirdi. Bağlantı finally'de geri verilir.
• 29. satır: throw hata betiği durdurur. Bozuk bir göçten sonra sıradakileri çalıştırmak, yamaları atlayarak yüklemek gibidir.

Betiği iki kez çalıştır:

PS C:\kod\pg-api> node --env-file=.env goc.jsUygulandı: 001_oyuncu_seviye.sqlUygulandı: 002_maclar_indeks.sqlGöçler tamam.PS C:\kod\pg-api> node --env-file=.env goc.jsGöçler tamam.

İkinci çalıştırmada hiçbir şey olmadı; iki dosya da tabloda yazılı. Takım arkadaşın projeyi indirip aynı komutu kendi veritabanında çalıştırdığında ise ikisi de uygulanır. Herkesin veritabanı aynı yamaya gelir.

Şimdi üçüncü göçü yaz; oyuncuların gerçek seviyelerini dolduralım:

1UPDATE oyuncular SET seviye = 87 WHERE ad = 'Deniz';2UPDATE oyuncular SET seviye = 142 WHERE ad = 'Ece';3UPDATE oyuncular SET seviye = 35 WHERE ad = 'Mert';4UPDATE oyuncular SET seviye = 210 WHERE ad = 'Selin';

Yazarken üçüncü satırda seviye yerine sevye yazdığını düşün. Betik ilk iki UPDATE'i çalıştırır, üçüncüde hata alır:

PS C:\kod\pg-api> node --env-file=.env goc.jsC:\kod\pg-api\node_modules\pg\lib\client.js:694          Error.captureStackTrace(err)                ^ error: column "sevye" of relation "oyuncular" does not exist    at C:\kod\pg-api\node_modules\pg\lib\client.js:694:17    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/pg-api/goc.js:23:9 {  ...}

ROLLBACK sayesinde Deniz ile Ece'nin seviyesi de geri alındı: beş oyuncunun seviyesi hâlâ 1 ve goc_gecmisi'nde 003 yok. Dosya henüz uygulanmadığı için onu düzeltmek serbest. Düzelt ve yeniden çalıştır:

PS C:\kod\pg-api> node --env-file=.env goc.jsUygulandı: 003_seviyeleri_doldur.sqlGöçler tamam.

Göçlerle çalışırken dört kural:

• Uygulanmış bir dosyayı değiştirme, adını da değiştirme. Değişiklik gerekiyorsa yeni bir dosya yaz (Görev 5'te adını değiştirmenin ne yaptığını göreceksin).
• schema.sql ilk kurulumun hikâyesi olarak kalır; bundan sonraki her değişiklik goclar klasörüne gider. Sıfırdan başlayan bir projede ilk göç dosyası tabloları kuran dosyanın kendisi olur.
• Canlı veritabanında göç çalıştırmadan önce yedek al (Ders 35). Neon'da veritabanının anında bir kopyasını (branch) açıp göçü önce orada deneyebilirsin.
• Neon, göç araçları için havuzsuz (direct) bağlantıyı öneriyor; bazı araçlar havuzlu bağlantının desteklemediği oturum özelliklerini kullanıyor. Connect penceresinde Connection pooling anahtarını kapatınca adresin -pooler'sız hâli gelir. Bizim betik o özelliklerin hiçbirini kullanmıyor.

Gerçek projelerde bu betiği kendin yazmazsın; aynı işi yapan hazır araçlar var: node-pg-migrate, Drizzle'ın drizzle-kit'i, Prisma'nın Prisma Migrate'i. Hepsinin çekirdeği bu derstekiyle aynı: numaralı dosyalar ve uygulananları tutan bir tablo.

#Neon'un sunucusuz sürücüsü

Neon'un kendi sürücüsü de var: @neondatabase/serverless (bu ders yazılırken 1.2.0). pg gibi kalıcı bir bağlantı açmak yerine sorguyu bir HTTP isteğiyle (ya da WebSocket üzerinden) gönderir. Ders 32'de gördüğün sunucusuz ortamlar için yapılmıştır: her istekte yeniden başlayan kısa ömürlü fonksiyonlarda havuz yaşayamaz, bazı ortamlarda kalıcı bağlantı açmak hiç mümkün değildir.

import { neon } from "@neondatabase/serverless" const sql = neon(process.env.DATABASE_URL)const ad = "x' OR '1'='1"const satirlar = await sql`SELECT id, ad FROM oyuncular WHERE ad = ${ad}`

Sorgu ters tırnakla yazılmış, ama başında sql adı var: bu bir etiketli şablon (tagged template). JavaScript bu kez metni kendisi birleştirmez; parçaları ve değerleri sql fonksiyonuna ayrı ayrı verir, sürücü de ${ad}'ı $1'e çevirir. Sürücünün içine bakıp göndereceği sorguyu yazdırdığımızda (ağa hiç çıkmadan) gördüğümüz buydu:

{  query: 'SELECT id, ad FROM oyuncular WHERE ad = $1',  params: [ "x' OR '1'='1" ]}

Yani başında sql olan şablon güvenli, pool.query(`... ${ad} ...`) güvenli değil. Aradaki tek fark baştaki o sözcük; kodu okurken dikkat et. Sürücünün 1.0 sürümünden beri sql'i düz fonksiyon gibi çağırmak hata verir:

This function can now be called only as a tagged-template function: sql`SELECT ${value}`, not sql("SELECT $1", [value], options). For a conventional function call with value placeholders ($1, $2, etc.), use sql.query("SELECT $1", [value], options).

Hangisini ne zaman kullanmalı? Neon'un kendi rehberi, sürekli çalışan bir sunucu için (bu dersteki Express API'si gibi) pg ve bağlantı havuzunu öneriyor: havuz istekler arasında yaşadığı için en hızlı yol bu. Her isteği ayrı, kısa ömürlü bir fonksiyonun karşıladığı ortamlarda Neon'un sürücüsü öne çıkar. Blok 6'da Next.js ile veritabanına bağlanırken bu ayrımı yeniden düşüneceksin.

#ORM'leri tanımak

Bu derste SQL'i elle yazdın, sonucu elle JSON'a çevirdin, göçleri elle numaralandırdın. Birçok proje bu işlerin bir kısmını bir ORM'e bırakır.

İki yaygın örnek. Kurmana gerek yok; nasıl göründüklerini tanı. Drizzle'da tablo kodda tarif edilir ve sorgu SQL'e çok benzer:

import { pgTable, integer, text } from "drizzle-orm/pg-core"import { drizzle } from "drizzle-orm/node-postgres"import { eq } from "drizzle-orm" const oyuncular = pgTable("oyuncular", {    id: integer().primaryKey().generatedAlwaysAsIdentity(),    ad: text().notNull().unique(),    bolge: text().notNull()}) const db = drizzle(process.env.DATABASE_URL)const trOyunculari = await db.select().from(oyuncular).where(eq(oyuncular.bolge, "TR"))

Bu örneği drizzle-orm 0.45.4 ile kendi veritabanımızda çalıştırdık; TR bölgesindeki oyuncular pg'deki gibi obje dizisi olarak geldi. Sorgunun sonuna await yerine .toSQL() eklersen Drizzle'ın Postgres'e göndereceği SQL'i görürsün. Değer yine metnin içinde değil, ayrı bir parametre:

{  sql: 'select "id", "ad", "bolge" from "oyuncular" where "oyuncular"."bolge" = $1',  params: [ 'TR' ]}

Prisma'da tablolar kendi şema dosyasında (schema.prisma) tarif edilir; Prisma bu dosyadan sana özel bir sorgu kütüphanesi üretir. Prisma 7'de bir sorgu şöyle görünür:

const trOyunculari = await prisma.oyuncu.findMany({ where: { bolge: "TR" } })

Bu ders yazılırken Prisma'nın 8. sürümü aday sürümdeydi (release candidate) ve npm install prisma bu aday sürümü kuruyordu. Sorgu yazımı da değişiyor: aynı sorgu .where({ bolge: "TR" }).all() biçimini alıyor. Kullanacağın gün güncel belgesine bak.

Ne zaman hangisi? SQL'i öğrenirken ve küçük projelerde pg ile elle SQL: ne olduğunu her an görürsün. TypeScript'e geçtiğinde (Blok 6), tablolarının tipleri koda kendiliğinden gelsin istediğinde ve ekip büyüdüğünde ORM'ler işini kolaylaştırır; iş ilanlarında Prisma ve Drizzle adlarını sık göreceksin.

Hangisini seçersen seç iki şey değişmez. Birincisi, ORM'ler değerleri arka planda parametre olarak gönderir ama "ham SQL" kapıları (adında çoğu zaman raw ya da unsafe geçer) bu korumayı kaldırır. İkincisi, yavaş bir sorguyu düzeltmek için yine SQL okuman gerekir.

#Görevler

Görevler esyalar adlı yeni bir tabloyla çalışıyor. SQL Editor'de pgapi veritabanı seçiliyken şu betiği çalıştır ve esyalar.sql adıyla projene kaydet:

1CREATE TABLE esyalar (2    id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,3    ad text NOT NULL UNIQUE,4    fiyat integer NOT NULL CHECK (fiyat >= 0),5    tur text NOT NULL6);7 8INSERT INTO esyalar (ad, fiyat, tur) VALUES9    ('Doran Kılıcı', 450, 'saldırı'),10    ('Doran Kalkanı', 450, 'savunma'),11    ('Uzun Kılıç', 350, 'saldırı'),12    ('Can İksiri', 50, 'tüketim'),13    ('Büyü Kitabı', 435, 'büyü'),14    ('Sonsuzluk Kılıcı', 3450, 'saldırı');

Görev 1 ve 2 için ayrı dosyalar yazıp node --env-file=.env dosya.js ile çalıştır; Görev 3 ve 4'te app.js'e route ekle. Önce kendin dene, takılırsan ipuçlarını sırayla aç.

Can İksiri: 50 altınUzun Kılıç: 350 altın

1import { pool } from "./db.js"2 3const sinir = 4004const { rows } = await pool.query(5    "SELECT ad, fiyat FROM esyalar WHERE fiyat <= $1 ORDER BY fiyat, ad",6    [sinir]7)8if (rows.length === 0) {9    console.log("Bu fiyata eşya yok")10}11for (const esya of rows) {12    console.log(`${esya.ad}: ${esya.fiyat} altın`)13}14await pool.end()

Can İksiri: 50 altınUzun Kılıç: 350 altın

{ adet: 3, ortalama: 1417 }

1import { pool } from "./db.js"2 3const tur = "saldırı"4const { rows } = await pool.query(5    "SELECT count(*)::int AS adet, round(avg(fiyat))::int AS ortalama FROM esyalar WHERE tur = $1",6    [tur]7)8console.log(rows[0])9await pool.end()

{ adet: 3, ortalama: 1417 }

1app.get("/esyalar/:id", async (req, res) => {2    const { rows } = await pool.query(3        "SELECT id, ad, fiyat, tur FROM esyalar WHERE id = $1",4        [req.params.id]5    )6    if (rows.length === 0) {7        return res.status(404).json({ hata: "Eşya bulunamadı" })8    }9    res.json(rows[0])10})11 12app.post("/esyalar", async (req, res) => {13    const { ad, fiyat, tur } = req.body14    const { rows } = await pool.query(15        "INSERT INTO esyalar (ad, fiyat, tur) VALUES ($1, $2, $3) RETURNING id, ad, fiyat, tur",16        [ad, fiyat, tur]17    )18    res.status(201).json(rows[0])19})

11    if (hata.code === "22P02" || hata.code === "22003" || hata.code === "23502" || hata.code === "23514") {

PS C:\kod\pg-api> curl.exe http://localhost:3000/esyalar/1{"id":1,"ad":"Doran Kılıcı","fiyat":450,"tur":"saldırı"}PS C:\kod\pg-api> curl.exe http://localhost:3000/esyalar/99{"hata":"Eşya bulunamadı"}PS C:\kod\pg-api> curl.exe http://localhost:3000/esyalar/abc{"hata":"Gönderilen değerlerden biri geçersiz"}PS C:\kod\pg-api> curl.exe http://localhost:3000/esyalar/1.5{"hata":"Gönderilen değerlerden biri geçersiz"}PS C:\kod\pg-api> curl.exe http://localhost:3000/esyalar/2147483648{"hata":"Gönderilen değerlerden biri geçersiz"}PS C:\kod\pg-api> curl.exe --json "@zirh.json" http://localhost:3000/esyalar{"id":7,"ad":"Kumaş Zırh","fiyat":300,"tur":"savunma"}PS C:\kod\pg-api> curl.exe --json "@zirh.json" http://localhost:3000/esyalar{"hata":"Bu kayıt zaten var"}PS C:\kod\pg-api> curl.exe --json "@eksi-fiyat.json" http://localhost:3000/esyalar{"hata":"Gönderilen değerlerden biri geçersiz"}

PS C:\kod\pg-api> curl.exe "http://localhost:3000/esyalar?ara=doran"[{"id":2,"ad":"Doran Kalkanı","fiyat":450},{"id":1,"ad":"Doran Kılıcı","fiyat":450}]PS C:\kod\pg-api> curl.exe "http://localhost:3000/esyalar?ara=doran&sirala=fiyat"[{"id":1,"ad":"Doran Kılıcı","fiyat":450},{"id":2,"ad":"Doran Kalkanı","fiyat":450}]PS C:\kod\pg-api> curl.exe "http://localhost:3000/esyalar?sirala=fiyat;DROP%20TABLE%20esyalar"{"hata":"sirala yalnız ad ya da fiyat olabilir"}

1app.get("/esyalar", async (req, res) => {2    const sirala = req.query.sirala ?? "ad"3    if (!["ad", "fiyat"].includes(sirala)) {4        return res.status(400).json({ hata: "sirala yalnız ad ya da fiyat olabilir" })5    }6    const ara = req.query.ara ?? ""7    const { rows } = await pool.query(8        `SELECT id, ad, fiyat FROM esyalar WHERE ad ILIKE $1 ORDER BY ${sirala}, id`,9        [`%${ara}%`]10    )11    res.json(rows)12})

Uygulandı: 004_esya_stok.sqlGöçler tamam.

1ALTER TABLE esyalar ADD COLUMN stok integer NOT NULL DEFAULT 10 CHECK (stok >= 0);

PS C:\kod\pg-api> node --env-file=.env goc.jsUygulandı: 004_esya_stok.sqlGöçler tamam.PS C:\kod\pg-api> node --env-file=.env goc.jsGöçler tamam.

PS C:\kod\pg-api> node --env-file=.env goc.js...error: column "stok" of relation "esyalar" already exists

#Kendini sına

pool.query("SELECT id, ad FROM oyuncular WHERE ad = '" + ad + "'")pool.query(`SELECT id, ad FROM oyuncular WHERE ad = '${ad}'`)pool.query("SELECT id, ad FROM oyuncular WHERE ad = $1", [ad])

await pool.query("BEGIN")await pool.query("UPDATE oyuncular SET seviye = seviye + 1 WHERE id = $1", [id])await pool.query("COMMIT")

#Kayıt noktası

pg-api yeni bir proje, bu yüzden Git'i burada yeniden başlatıyorsun. Kaydetmeden önce git status ile listeye bak: .env ve node_modules orada olmamalı.

Bir sonraki ders Blok 5'in projesi: takım API'sini JSON dosyasından PostgreSQL'e taşıyacak, ilişkili tablolar, sayfalama, arama ve transaction gerektiren bir işlem ekleyip yayına alacaksın.