Skip to main content
Access PostgreSQL databases from Python applications using standard PostgreSQL libraries with automatically injected connection strings.

​
Connection String Injection

Suga automatically injects database connection strings as environment variables for services with database access:
suga.yaml
databases:
  main:
    subtype: neon
    access:
      api: [query]
    env_var_key: DATABASE_URL
The api service automatically receives DATABASE_URL containing the full connection string.

​
Using psycopg2

pip install psycopg2-binary

import psycopg2
import os

# Connection string automatically injected by Suga
conn = psycopg2.connect(os.environ['DATABASE_URL'])
cursor = conn.cursor()

# Query with parameters
cursor.execute('SELECT * FROM users WHERE active = %s', [True])
users = cursor.fetchall()

# Insert data
cursor.execute(
    'INSERT INTO users (name, email) VALUES (%s, %s)',
    ['Alice', 'alice@example.com']
)
conn.commit()

# Update data
cursor.execute(
    'UPDATE users SET name = %s WHERE id = %s',
    ['Bob', 1]
)
conn.commit()

# Delete data
cursor.execute('DELETE FROM users WHERE id = %s', [1])
conn.commit()

cursor.close()
conn.close()

​
Using SQLAlchemy ORM

pip install sqlalchemy psycopg2-binary

from sqlalchemy import create_engine, Column, Integer, String, Boolean
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
import os

# Connection string automatically injected by Suga
engine = create_engine(os.environ['DATABASE_URL'])
Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
    active = Column(Boolean, default=True)

Session = sessionmaker(bind=engine)
session = Session()

# Query
users = session.query(User).filter(User.active == True).all()

# Insert
user = User(name='Alice', email='alice@example.com')
session.add(user)
session.commit()

# Update
user = session.query(User).filter(User.id == 1).first()
user.name = 'Bob'
session.commit()

​
Using Django ORM

settings.py
import os
import dj_database_url

DATABASES = {
    'default': dj_database_url.config(
        default=os.environ['DATABASE_URL'],
        conn_max_age=600
    )
}

pip install dj-database-url psycopg2-binary

​
Multiple Databases

When accessing multiple databases, each has a unique environment variable:
suga.yaml
databases:
  users:
    access:
      api: [query]
    env_var_key: USERS_DATABASE_URL

  products:
    access:
      api: [query]
    env_var_key: PRODUCTS_DATABASE_URL

import psycopg2
import os

# Connect to different databases
users_conn = psycopg2.connect(os.environ['USERS_DATABASE_URL'])
products_conn = psycopg2.connect(os.environ['PRODUCTS_DATABASE_URL'])

# Query different databases
users_cursor = users_conn.cursor()
users_cursor.execute('SELECT * FROM users')
users = users_cursor.fetchall()

products_cursor = products_conn.cursor()
products_cursor.execute('SELECT * FROM products')
products = products_cursor.fetchall()

​
Connection Pooling

Use connection pooling for better performance: 
from psycopg2 import pool
import os

# Create connection pool
connection_pool = pool.SimpleConnectionPool(
    1, 20,  # Min and max connections
    os.environ['DATABASE_URL']
)

# Get connection from pool
conn = connection_pool.getconn()
cursor = conn.cursor()
cursor.execute('SELECT * FROM users')

# Return connection to pool
connection_pool.putconn(conn)

​
Learn More

Database Configuration

Learn about database setup

Database Migrations

Manage schema changes