Skip to main content
Returns the contents of a file as a data URL suitable for inline embedding.

​
Signature

sqlpage.read_file_as_data_url(file_path TEXT) -> TEXT

​
Parameters

​
file_path
TEXT
required
Path to the file to read, relative to the web root directory

​
Return Value

​
return
TEXT
A data URL containing the file contents (e.g., data:image/png;base64,iVBOR...), or NULL if the parameter is NULL

​
Description

The read_file_as_data_url() function reads a file and converts it to a data URL. Data URLs embed file contents directly in HTML, eliminating separate HTTP requests for images, documents, or other resources. The MIME type is automatically detected from:
  1. Uploaded file metadata (if path is from sqlpage.uploaded_file_path())
  2. File extension
Note: Data URLs are larger than the original files (~33% overhead for base64 encoding). Use only for small files (< 100 KB).

​
Examples

​
Display Inline Image

Embed an image directly in a card: 
SELECT 'card' as component;
SELECT 
    'Product Image' as title,
    sqlpage.read_file_as_data_url('images/product.jpg') as top_image,
    'High quality product' as description;

​
Store Uploaded Image

Save an uploaded file as a data URL in the database: 
INSERT INTO products (name, image_data)
VALUES (
    :product_name,
    sqlpage.read_file_as_data_url(sqlpage.uploaded_file_path('image'))
);

SELECT 'redirect' as component, '/products.sql' as link;

​
Display Stored Images

Show images stored as data URLs: 
SELECT 'card' as component;
SELECT 
    name as title,
    image_data as top_image,
    price as description
FROM products;

​
Inline Icons

Embed small icons: 
SELECT 'list' as component;
SELECT 
    name as title,
    sqlpage.read_file_as_data_url('icons/' || icon_name || '.svg') as icon_url
FROM categories;

​
Email with Embedded Images

Create email content with inline images: 
SET logo_data = sqlpage.read_file_as_data_url('images/logo.png');

-- Use in email HTML
SET email_html = '<img src="' || $logo_data || '" alt="Logo">';

​
Downloadable Files

Provide files as downloadable links: 
SELECT 'button' as component;
SELECT 
    'Download ' || filename as title,
    sqlpage.read_file_as_data_url('documents/' || filename) as link,
    'download' as icon
FROM available_documents;

​
Display PDF Preview

Embed PDF in an iframe: 
SET pdf_data = sqlpage.read_file_as_data_url('documents/report.pdf');

SELECT 'text' as component,
    '<iframe src="' || $pdf_data || '" width="100%" height="600"></iframe>' as html;

​
Avatar Images

Store and display user avatars: 
-- Store avatar on upload
UPDATE users
SET avatar = sqlpage.read_file_as_data_url(sqlpage.uploaded_file_path('avatar'))
WHERE id = :user_id;

-- Display avatar
SELECT 'card' as component;
SELECT 
    username as title,
    email as description,
    avatar as image
FROM users;

​
MIME Type Detection

​
From File Extension

Common file extensions and their MIME types: 
-- Images
sqlpage.read_file_as_data_url('image.jpg')   -- data:image/jpeg;base64,...
sqlpage.read_file_as_data_url('image.png')   -- data:image/png;base64,...
sqlpage.read_file_as_data_url('image.gif')   -- data:image/gif;base64,...
sqlpage.read_file_as_data_url('image.svg')   -- data:image/svg+xml;base64,...
sqlpage.read_file_as_data_url('image.webp')  -- data:image/webp;base64,...

-- Documents
sqlpage.read_file_as_data_url('doc.pdf')     -- data:application/pdf;base64,...
sqlpage.read_file_as_data_url('data.json')   -- data:application/json;base64,...
sqlpage.read_file_as_data_url('page.html')   -- data:text/html;base64,...
sqlpage.read_file_as_data_url('file.txt')    -- data:text/plain;base64,...

​
From Uploaded File

For uploaded files, uses the MIME type from the browser: 
SET upload_path = sqlpage.uploaded_file_path('document');
-- Uses MIME type from browser's Content-Type header
SET data_url = sqlpage.read_file_as_data_url($upload_path);

​
Data URL Format

Data URLs follow this format: 
data:[MIME-type];base64,[base64-encoded-data]
Example: 
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
│    │         │       │
│    │         │       └── Base64-encoded file content
│    │         └────────── Encoding type
│    └───────────────────── MIME type
└─────────────────────────── Scheme

​
Size Considerations

​
Base64 Overhead

Base64 encoding increases file size by ~33%: 
Original:  10 KB
Base64:    13.3 KB
Data URL:  13.3 KB + MIME type header
File TypeMax SizeReason
Icons10 KBFast loading, minimal overhead
Thumbnails50 KBAcceptable for previews
Images100 KBBalance between size and convenience
Documents200 KBLarger files better served separately

​
Check File Size

For large files, use regular URLs instead: 
-- Check uploaded file size
SET file_path = sqlpage.uploaded_file_path('image');
SET file_size = (SELECT LENGTH(content) FROM files WHERE path = $file_path);

SELECT 'redirect' as component,
    '/error.sql?msg=file_too_large' as link
WHERE $file_size > 102400;  -- 100 KB limit

-- Store as data URL if small enough
INSERT INTO images (data) 
VALUES (sqlpage.read_file_as_data_url($file_path));

​
Use Cases

​
When to Use Data URLs

  1. Small images - Icons, avatars, thumbnails
  2. Database storage - Keeping files with their data
  3. Email content - Embedded images in HTML emails
  4. Offline access - Single HTML file with embedded resources
  5. Reduced requests - Eliminate HTTP round trips
  6. Temporary files - Display uploaded files before storage

​
When NOT to Use Data URLs

  1. Large files - Photos, videos, PDFs > 100 KB
  2. Cacheable resources - Files shared across pages
  3. External resources - Better served via CDN
  4. Frequently changing - Regular files easier to update

​
Security Considerations

​
Validate File Types

Restrict allowed file types: 
SET mime_type = sqlpage.uploaded_file_mime_type('image');

SELECT 'redirect' as component,
    '/error.sql?msg=invalid_type' as link
WHERE $mime_type NOT IN ('image/jpeg', 'image/png', 'image/gif', 'image/webp');

SET file_data = sqlpage.read_file_as_data_url(sqlpage.uploaded_file_path('image'));

​
File Size Limits

Prevent large file uploads: 
-- Enforce size limit before converting to data URL
SET file_path = sqlpage.uploaded_file_path('document');

-- Check size (implementation depends on your setup)
SELECT 'redirect' as component,
    '/error.sql?msg=too_large' as link
WHERE LENGTH($file_path) > 102400;

​
Sanitize Paths

Prevent path traversal: 
-- DANGEROUS
SELECT sqlpage.read_file_as_data_url(:user_path);

-- SAFER
SET safe_path = 'images/' || REPLACE(REPLACE(:filename, '..', ''), '/', '') || '.png';
SELECT sqlpage.read_file_as_data_url($safe_path);

​
Database Storage Example

Complete example of storing and retrieving images: 
-- Create table
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    image_data TEXT,  -- Data URL
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Upload form
SELECT 'form' as component,
    'upload_product.sql' as action;
SELECT 'name' as name, 'text' as type, 'Product Name' as label;
SELECT 'image' as name, 'file' as type, 'Image' as label;

-- Handle upload
INSERT INTO products (name, image_data)
VALUES (
    :name,
    sqlpage.read_file_as_data_url(sqlpage.uploaded_file_path('image'))
)
RETURNING
    'redirect' as component,
    '/products.sql' as link;

-- Display products
SELECT 'card' as component;
SELECT 
    name as title,
    image_data as top_image
FROM products;

​
Performance Tips

  1. Cache data URLs - Store converted URLs in database
  2. Limit file sizes - Enforce maximum file size
  3. Use thumbnails - Generate smaller versions for lists
  4. Lazy loading - Load data URLs on demand
  5. Consider CDN - For larger or frequently accessed files

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us