{
  "schemaVersion": "1.0",
  "canonicalPage": "https://fileformat.co/ext/duckdb",
  "inspectorUrl": "https://fileformat.co/inspect",
  "spec": {
    "slug": "duckdb",
    "extension": ".duckdb",
    "aliases": [],
    "name": "DuckDB Analytical Database File",
    "shortName": "DuckDB",
    "category": "data-lake",
    "tier": 2,
    "summary": "Single-file vectorized OLAP database format storing compressed columnar row-groups in 4 KB / 256 KB block-managed pages.",
    "technicalNotes": "Unlike SQLite, DuckDB places an 8-byte checksum preamble at `0x00..0x07` and writes its 4-byte ASCII magic `'DUCK'` (`44 55 43 4B`) at offset **`0x08`**, followed by `uint64_le` storage version!",
    "mimeTypes": [
      "application/vnd.duckdb",
      "application/octet-stream"
    ],
    "identifiers": {
      "specUrl": "https://duckdb.org/docs/internals/storage.html"
    },
    "binarySignature": {
      "endianness": "little",
      "magicBytes": [
        {
          "offset": 8,
          "hex": "44 55 43 4B",
          "ascii": "DUCK",
          "description": "4-byte 'DUCK' magic at offset 0x08 after 8-byte checksum"
        }
      ],
      "containerFamily": null,
      "headerLayout": [
        {
          "offset": "0x00 - 0x07",
          "byteOffset": 0,
          "byteLength": 8,
          "lengthLabel": "8 B",
          "dataType": "uint64_le",
          "fieldName": "checksum",
          "description": "64-bit block checksum of main header"
        },
        {
          "offset": "0x08 - 0x0B",
          "byteOffset": 8,
          "byteLength": 4,
          "lengthLabel": "4 B",
          "dataType": "char[4]",
          "fieldName": "magic",
          "description": "ASCII 'DUCK' identifier"
        },
        {
          "offset": "0x0C - 0x13",
          "byteOffset": 12,
          "byteLength": 8,
          "lengthLabel": "8 B",
          "dataType": "uint64_le",
          "fieldName": "version",
          "description": "DuckDB storage layout version (e.g. 64)"
        }
      ]
    },
    "securityProfile": {
      "riskLevel": "medium",
      "allowsArbitraryCodeOrMacros": false,
      "xxeRisk": false,
      "polyglotPrependRisk": false,
      "pickleDeserializationRisk": false,
      "uploadValidationNotes": "Open untrusted .duckdb files with enable_external_access=false and lock_configuration=true so embedded views cannot invoke read_parquet('http://...') SSRF."
    },
    "codeSnippets": {
      "python": "import struct, sys\nwith open(sys.argv[1], \"rb\") as f:\n    csum, magic, ver = struct.unpack(\"<Q4sQ\", f.read(20))\n    assert magic == b\"DUCK\"\n    print(f\"DuckDB storage version={ver}\")",
      "typescript": "export async function readDuckDbHeader(file: File) {\n  const buf = await file.slice(0, 20).arrayBuffer();\n  const magic = new TextDecoder().decode(buf.slice(8, 12));\n  const version = new DataView(buf).getBigUint64(12, true);\n  return { valid: magic === 'DUCK', version };\n}",
      "rust": "use std::{fs::File, io::Read};\nfn main() -> std::io::Result<()> {\n    let mut b = [0u8; 20];\n    File::open(std::env::args().nth(1).expect(\"usage: <prog> <file>\"))?.read_exact(&mut b)?;\n    println!(\"DuckDB magic={:?} v={}\", &b[8..12], u64::from_le_bytes(b[12..20].try_into().expect(\"fixed-size byte window\")));\n    Ok(())\n}",
      "go": "package main\nimport (\"encoding/binary\"; \"fmt\"; \"io\"; \"os\")\nfunc main() {\n    f, err := os.Open(os.Args[1])\n    if err != nil {\n        fmt.Fprintln(os.Stderr, \"open:\", err)\n        os.Exit(1)\n    }\n    defer f.Close()\n    b := make([]byte, 20)\n    if _, err := io.ReadFull(f, b); err != nil {\n        fmt.Fprintln(os.Stderr, \"read:\", err)\n        os.Exit(1)\n    }\n    fmt.Printf(\"DuckDB %s v%d\\n\", string(b[8:12]), binary.LittleEndian.Uint64(b[12:20]))\n}"
    },
    "relatedFormats": [
      "sqlite",
      "parquet",
      "arrow"
    ],
    "verifiedAt": "2026-11-14T16:09:03Z"
  },
  "samples": [
    {
      "id": "duckdb-minimal",
      "filename": "minimal-v64.duckdb",
      "variant": "minimal",
      "title": "Minimal DuckDB Database File",
      "description": "Real single-table DuckDB database produced by duckdb.connect() — includes valid checksum preamble and DUCK magic.",
      "localPath": "/fixtures/v1/duckdb/minimal-v64.duckdb",
      "cdnUrl": "https://fileformat.co/fixtures/v1/duckdb/minimal-v64.duckdb",
      "sizeBytes": 536576,
      "sha256": "465f054e7e501c946c263070389322a8f1f96195ab9bb115a1e80d34401298f5",
      "expectValid": true
    },
    {
      "id": "duckdb-realistic",
      "filename": "analytics-store.duckdb",
      "variant": "realistic",
      "title": "Multi-Table DuckDB Analytics Store",
      "description": "Real DuckDB database with two tables, primary keys, and a secondary index.",
      "localPath": "/fixtures/v1/duckdb/analytics-store.duckdb",
      "cdnUrl": "https://fileformat.co/fixtures/v1/duckdb/analytics-store.duckdb",
      "sizeBytes": 1585152,
      "sha256": "92b98fd5e4954d171d464a36c6cfe175d15e12d09f8492382ed11458fdeb8278",
      "expectValid": true
    },
    {
      "id": "duckdb-edge-case",
      "filename": "truncated-header.duckdb",
      "variant": "edge-case",
      "title": "Truncated 20-Byte DuckDB Header",
      "description": "First 20 bytes of a real DuckDB file — duckdb.connect() must raise 'not a valid DuckDB database file'.",
      "localPath": "/fixtures/v1/duckdb/truncated-header.duckdb",
      "cdnUrl": "https://fileformat.co/fixtures/v1/duckdb/truncated-header.duckdb",
      "sizeBytes": 20,
      "sha256": "b9fb1ef9dc5827bddb7c61b93433aea5cdbcb75d63941f72704906f6ddeb45b8",
      "expectValid": false,
      "edgeCaseTag": "Unaligned 20B Truncation"
    }
  ]
}