std.db

std.db gir deg tilgang til databaser med et lite, kjent sett funksjoner. Du åpner en tilkobling, kjører SQL-setninger, henter verdier og rader, og styrer transaksjoner — akkurat det du forventer, uten seremoni.

Standardvalget er NorsDB, den lettvekts databasen som følger med kjøretiden, men grensesnittet er det samme uansett motor. For data som kommer utenfra finnes bundne varianter som holder verdiene atskilt fra selve setningen, slik at en ondsinnet inndata ikke kan endre spørringen.

Når bruker du den

Bruk std.db når appen din trenger å lagre data som varer. Du åpner en tilkobling med open, kjører setninger med execute, henter verdier med query_text og query_int, og pakker flere endringer i en transaksjon med begin, commit og rollback — eller lar transaction gjøre det for deg.

Slik kommer du i gang

bruk std.db som db

funksjon start() -> heiltall {
    la h = db.open("data.norsdb")
    db.execute(h, "CREATE TABLE IF NOT EXISTS notat (id INTEGER, tekst TEXT)")
    db.execute_bundet(h, "INSERT INTO notat (id, tekst) VALUES (?, ?)", ["1", "hei"])
    la tal = db.query_int(h, "SELECT COUNT(*) FROM notat")
    skriv(tekst(tal))
    db.close(h)
    returner 0
}

Bruk execute_bundet med ?-plassholdere for verdier som kommer utenfra — det holder dataene atskilt fra SQL-en og stopper injeksjon. Lukk tilkoblingen med close når du er ferdig.

Funksjonene

Arbeidsflyten er alltid den samme: åpne (open), kjøre (execute, query_text, query_int, query_rader), og lukke (close). De bundne variantene (*_bundet) er de du bør bruke for verdier utenfra. Transaksjoner styres med begin, commit og rollback, eller samlet med transaction. En pool (pool, pool_acquire) lar deg gjenbruke tilkoblinger under last.

• backend() -> tekst — Navnet på databasemotoren som er i bruk.
• status() -> ordbok_tekst — Statusinformasjon om databasen.
• open(sti: tekst) -> ordbok_tekst — Åpner en databasetilkobling til stien og gir et håndtak.
• close(handle) -> bool — Lukker en tilkobling.
• execute(handle, sql: tekst) -> heltall — Kjører en SQL-setning som endrer data (INSERT, UPDATE, CREATE …).
• query_text(handle, sql: tekst) -> tekst — Kjører en spørring og gir første verdi som tekst.
• query_int(handle, sql: tekst) -> heltall — Kjører en spørring og gir første verdi som heltall.
• query_rader(handle, sql: tekst) -> tekst — Henter flere rader som tekst.
• siste_feil(handle) -> tekst — Siste feilmelding fra databasen.
• execute_bundet(handle, sql: tekst, params: liste<tekst>) -> heltall — Som execute, men med bundne parametre (?) — trygt mot injeksjon.
• query_text_bundet(handle, sql: tekst, params: liste<tekst>) -> tekst — Tekst-spørring med bundne parametre.
• query_int_bundet(handle, sql: tekst, params: liste<tekst>) -> heltall — Tall-spørring med bundne parametre.
• migrate(handle, skript: tekst) -> heltall — Kjører et migrasjonsskript mot databasen.
• transaction(handle, skript: tekst) -> heltall — Kjører et skript som én transaksjon — alt eller ingenting.
• pool(sti: tekst, maks: heltall) -> ordbok_tekst — Oppretter en tilkoblingspool med gitt maksstørrelse.
• pool_acquire(pool) -> ordbok_tekst — Henter en tilkobling fra poolen.
• pool_size(pool) -> heltall — Antall tilkoblinger i poolen.
• pool_close(pool) -> bool — Lukker poolen og alle tilkoblingene.
• begin(handle) -> bool — Starter en transaksjon.
• commit(handle) -> bool — Fullfører og lagrer en transaksjon.
• rollback(handle) -> bool — Angrer alle endringer i en transaksjon.
• ping(handle) -> bool — Sjekker at tilkoblingen fortsatt lever.
• backup(handle, sti: tekst) -> bool

Godt å vite

• Bruk alltid de bundne variantene (execute_bundet, query_text_bundet) for verdier utenfra — det er det viktigste enkelttiltaket mot SQL-injeksjon.
• Pakk sammensatte endringer i en transaksjon, så unngår du halvferdige tilstander hvis noe feiler midtveis.
• Lukk tilkoblinger med close når du er ferdig, eller bruk en pool for gjenbruk under last.

std.db er én av modulene i standardbiblioteket. Alt følger med kjøretiden — ingen installasjon, ingen eksterne avhengigheter. Se også Dokumentasjon for språket og kjøretiden.

Tilbake til oversikten